@redthreadlabs/tracelog-client 1.3.0

package/dist/EventBuilder.d.ts

@@ -0,0 +1,21 @@
+import { JsonValue, LogEventItem } from './types';
+export type EventEnqueuer = (event: LogEventItem) => void;
+export declare class EventBuilder {
+    private _enqueue;
+    private _type;
+    private _level;
+    private _message;
+    private _duration?;
+    private _error?;
+    private _params?;
+    constructor(enqueue: EventEnqueuer, type: string);
+    info(message: string): this;
+    warn(message: string): this;
+    error(message: string): this;
+    debug(message: string): this;
+    withParam(key: string, value: JsonValue): this;
+    withParams(params: Record<string, JsonValue>): this;
+    withError(err: any): this;
+    withDuration(ms: number): this;
+    send(): void;
+}

package/dist/EventBuilder.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBuilder = void 0;
+class EventBuilder {
+    constructor(enqueue, type) {
+        this._level = 'info';
+        this._message = '';
+        this._enqueue = enqueue;
+        this._type = type;
+    }
+    info(message) {
+        this._level = 'info';
+        this._message = message;
+        return this;
+    }
+    warn(message) {
+        this._level = 'warn';
+        this._message = message;
+        return this;
+    }
+    error(message) {
+        this._level = 'error';
+        this._message = message;
+        return this;
+    }
+    debug(message) {
+        this._level = 'debug';
+        this._message = message;
+        return this;
+    }
+    withParam(key, value) {
+        if (!this._params)
+            this._params = {};
+        this._params[key] = value;
+        return this;
+    }
+    withParams(params) {
+        if (!this._params)
+            this._params = {};
+        Object.assign(this._params, params);
+        return this;
+    }
+    withError(err) {
+        if (err instanceof Error) {
+            this._error = { message: err.message };
+            if (err.name)
+                this._error.type = err.name;
+            if (err.stack)
+                this._error.stack = err.stack;
+        }
+        else if (typeof err === 'string') {
+            this._error = { message: err };
+        }
+        else if (err != null) {
+            this._error = { message: String(err) };
+        }
+        return this;
+    }
+    withDuration(ms) {
+        this._duration = ms;
+        return this;
+    }
+    send() {
+        const event = {
+            type: this._type,
+            timestamp: Date.now(),
+            level: this._level,
+            message: this._message,
+        };
+        if (this._duration !== undefined)
+            event.duration = this._duration;
+        if (this._error)
+            event.error = this._error;
+        if (this._params)
+            event.params = this._params;
+        this._enqueue(event);
+    }
+}
+exports.EventBuilder = EventBuilder;

package/dist/LogClient.d.ts

@@ -0,0 +1,25 @@
+import { EventBuilder } from './EventBuilder';
+import { JsonValue, LogClientOptions, TimerToken } from './types';
+export declare class LogClient {
+    private _opts;
+    private _eventBuffer;
+    private _timerBuffer;
+    private _activeTimers;
+    private _flushTimer;
+    private _persistTimer;
+    private _disposed;
+    private _flushing;
+    constructor(opts: LogClientOptions);
+    event(type?: string): EventBuilder;
+    startTimer(name: string, parent?: TimerToken): TimerToken;
+    endTimer(token: TimerToken, context?: Record<string, JsonValue>): void;
+    flush(): Promise<void>;
+    dispose(): void;
+    private _enqueueEvent;
+    private _sendInChunks;
+    private _sendChunkWithRetry;
+    private _sendChunk;
+    private _schedulePersist;
+    private _persistNow;
+    private _loadPersistedLogs;
+}

package/dist/LogClient.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogClient = void 0;
+const EventBuilder_1 = require("./EventBuilder");
+// Default constants (matching the original AppLogRecorder)
+const DEFAULT_FLUSH_INTERVAL_MS = 5000;
+const DEFAULT_MAX_BUFFER_SIZE = 100;
+const DEFAULT_MAX_CHUNK_SIZE = 50;
+const DEFAULT_MAX_CHUNK_BYTES = 512 * 1024;
+const INTER_CHUNK_DELAY_MS = 200;
+const MAX_RETRIES = 3;
+const BASE_RETRY_DELAY_MS = 1000;
+const PERSIST_DEBOUNCE_MS = 100;
+class LogClient {
+    constructor(opts) {
+        this._eventBuffer = [];
+        this._timerBuffer = [];
+        this._activeTimers = new Map();
+        this._flushTimer = null;
+        this._persistTimer = null;
+        this._disposed = false;
+        this._flushing = false;
+        this._opts = opts;
+        this._loadPersistedLogs();
+        this._flushTimer = setInterval(() => this.flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS);
+    }
+    // ---- Fluent event builder ----
+    event(type = 'client-log') {
+        return new EventBuilder_1.EventBuilder((evt) => this._enqueueEvent(evt), type);
+    }
+    // ---- Perf timing ----
+    startTimer(name, parent) {
+        const id = randomHex(16);
+        const trace_id = parent ? parent.trace_id : randomHex(32);
+        const root_id = parent ? parent.root_id : id;
+        const token = { id, trace_id, root_id, key: name };
+        const active = {
+            token,
+            startTime: now(),
+            parentToken: parent,
+            children: [],
+        };
+        this._activeTimers.set(id, active);
+        // Register as child of parent
+        if (parent) {
+            const parentActive = this._activeTimers.get(parent.id);
+            if (parentActive) {
+                parentActive.children.push(id);
+            }
+        }
+        return token;
+    }
+    endTimer(token, context) {
+        const active = this._activeTimers.get(token.id);
+        if (!active)
+            return;
+        const duration = now() - active.startTime;
+        // Auto-close children that haven't been ended yet
+        for (const childId of active.children) {
+            const childActive = this._activeTimers.get(childId);
+            if (childActive) {
+                this.endTimer(childActive.token);
+            }
+        }
+        const timer = {
+            id: token.id,
+            trace_id: token.trace_id,
+            root_id: token.root_id,
+            name: token.key,
+            type: 'client-perf',
+            timestamp: Math.round(active.startTime),
+            duration: Math.round(duration),
+            outcome: 'success',
+        };
+        if (active.parentToken) {
+            timer.parent_id = active.parentToken.id;
+        }
+        if (context && Object.keys(context).length > 0) {
+            timer.context = { tags: context };
+        }
+        this._timerBuffer.push(timer);
+        this._activeTimers.delete(token.id);
+        this._schedulePersist();
+        // Force flush if buffer is getting large
+        if (this._timerBuffer.length + this._eventBuffer.length >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE)) {
+            this.flush();
+        }
+    }
+    // ---- Transport ----
+    async flush() {
+        if (this._disposed || this._flushing)
+            return;
+        if (this._eventBuffer.length === 0 && this._timerBuffer.length === 0)
+            return;
+        this._flushing = true;
+        try {
+            const events = this._eventBuffer.splice(0);
+            const timers = this._timerBuffer.splice(0);
+            await this._sendInChunks(events, timers);
+        }
+        finally {
+            this._flushing = false;
+            this._schedulePersist();
+        }
+    }
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        if (this._flushTimer) {
+            clearInterval(this._flushTimer);
+            this._flushTimer = null;
+        }
+        if (this._persistTimer) {
+            clearTimeout(this._persistTimer);
+            this._persistTimer = null;
+        }
+        // Persist anything remaining
+        this._persistNow();
+    }
+    // ---- Internal: event buffering ----
+    _enqueueEvent(event) {
+        if (this._disposed)
+            return;
+        this._eventBuffer.push(event);
+        this._schedulePersist();
+        if (this._eventBuffer.length >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE)) {
+            this.flush();
+        }
+    }
+    // ---- Internal: chunked sending ----
+    async _sendInChunks(events, timers) {
+        const maxChunkSize = this._opts.maxChunkSize ?? DEFAULT_MAX_CHUNK_SIZE;
+        const maxChunkBytes = this._opts.maxChunkBytes ?? DEFAULT_MAX_CHUNK_BYTES;
+        // Combine events and timers into chunks that respect size limits
+        let eventIdx = 0;
+        let timerIdx = 0;
+        let isFirstChunk = true;
+        while (eventIdx < events.length || timerIdx < timers.length) {
+            if (!isFirstChunk) {
+                await delay(INTER_CHUNK_DELAY_MS);
+            }
+            isFirstChunk = false;
+            const chunkEvents = [];
+            const chunkTimers = [];
+            let estimatedBytes = 200; // base overhead for batch envelope
+            // Fill chunk with events
+            while (eventIdx < events.length && chunkEvents.length + chunkTimers.length < maxChunkSize) {
+                const itemBytes = estimateJsonSize(events[eventIdx]);
+                if (estimatedBytes + itemBytes > maxChunkBytes && chunkEvents.length > 0)
+                    break;
+                chunkEvents.push(events[eventIdx]);
+                estimatedBytes += itemBytes;
+                eventIdx++;
+            }
+            // Fill chunk with timers
+            while (timerIdx < timers.length && chunkEvents.length + chunkTimers.length < maxChunkSize) {
+                const itemBytes = estimateJsonSize(timers[timerIdx]);
+                if (estimatedBytes + itemBytes > maxChunkBytes && (chunkEvents.length + chunkTimers.length) > 0)
+                    break;
+                chunkTimers.push(timers[timerIdx]);
+                estimatedBytes += itemBytes;
+                timerIdx++;
+            }
+            if (chunkEvents.length === 0 && chunkTimers.length === 0)
+                break;
+            await this._sendChunkWithRetry(chunkEvents, chunkTimers);
+        }
+    }
+    async _sendChunkWithRetry(events, timers) {
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                await this._sendChunk(events, timers);
+                return;
+            }
+            catch (err) {
+                if (attempt < MAX_RETRIES) {
+                    await delay(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                }
+                else {
+                    // Max retries exceeded — put items back for persistence
+                    this._eventBuffer.push(...events);
+                    this._timerBuffer.push(...timers);
+                    this._schedulePersist();
+                }
+            }
+        }
+    }
+    async _sendChunk(events, timers) {
+        const batch = {
+            client: this._opts.client,
+            events,
+            timers,
+        };
+        const userId = this._opts.getUserId?.();
+        const sessionRef = this._opts.getSessionRef?.();
+        const deviceId = this._opts.getDeviceId?.();
+        if (userId)
+            batch.user_id = userId;
+        if (sessionRef)
+            batch.session_ref = sessionRef;
+        if (deviceId)
+            batch.device_id = deviceId;
+        const headers = await Promise.resolve(this._opts.getAuthHeaders());
+        const response = await fetch(this._opts.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...headers,
+            },
+            body: JSON.stringify(batch),
+        });
+        if (!response.ok) {
+            throw new Error(`Server returned ${response.status}`);
+        }
+    }
+    // ---- Internal: persistence ----
+    _schedulePersist() {
+        if (this._persistTimer || !this._opts.persistLogs)
+            return;
+        this._persistTimer = setTimeout(() => {
+            this._persistTimer = null;
+            this._persistNow();
+        }, PERSIST_DEBOUNCE_MS);
+    }
+    _persistNow() {
+        if (!this._opts.persistLogs)
+            return;
+        if (this._eventBuffer.length === 0 && this._timerBuffer.length === 0) {
+            this._opts.persistLogs('').catch(() => { });
+            return;
+        }
+        const data = JSON.stringify({
+            events: this._eventBuffer,
+            timers: this._timerBuffer,
+        });
+        this._opts.persistLogs(data).catch(() => { });
+    }
+    async _loadPersistedLogs() {
+        if (!this._opts.loadPersistedLogs)
+            return;
+        try {
+            const data = await this._opts.loadPersistedLogs();
+            if (!data)
+                return;
+            const parsed = JSON.parse(data);
+            if (Array.isArray(parsed.events)) {
+                this._eventBuffer.push(...parsed.events);
+            }
+            if (Array.isArray(parsed.timers)) {
+                this._timerBuffer.push(...parsed.timers);
+            }
+            // Clear persisted data now that it's loaded
+            this._opts.persistLogs?.('').catch(() => { });
+        }
+        catch {
+            // Ignore parse errors from corrupted persisted data
+        }
+    }
+}
+exports.LogClient = LogClient;
+// ---- Helpers ----
+function randomHex(length) {
+    const chars = '0123456789abcdef';
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result += chars[Math.floor(Math.random() * 16)];
+    }
+    return result;
+}
+function now() {
+    if (typeof performance !== 'undefined' && performance.now) {
+        // Use performance.now() for high-res timing, but we need wall-clock for timestamps
+        // Store the offset on first call
+        if (!now._offset) {
+            now._offset = Date.now() - performance.now();
+        }
+        return now._offset + performance.now();
+    }
+    return Date.now();
+}
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function estimateJsonSize(obj) {
+    // Fast estimate — avoid full serialization during chunking
+    return JSON.stringify(obj).length;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { LogClient } from './LogClient';
+export { EventBuilder } from './EventBuilder';
+export { LogBatch, LogEventItem, TimerItem, ClientInfo, TimerToken, LogClientOptions, LogLevel, JsonValue, } from './types';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBuilder = exports.LogClient = void 0;
+var LogClient_1 = require("./LogClient");
+Object.defineProperty(exports, "LogClient", { enumerable: true, get: function () { return LogClient_1.LogClient; } });
+var EventBuilder_1 = require("./EventBuilder");
+Object.defineProperty(exports, "EventBuilder", { enumerable: true, get: function () { return EventBuilder_1.EventBuilder; } });

package/dist/types.d.ts

@@ -0,0 +1,115 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogBatch {
+    client: ClientInfo;
+    user_id?: string;
+    session_ref?: string;
+    device_id?: string;
+    events: LogEventItem[];
+    timers: TimerItem[];
+}
+export interface LogEventItem {
+    /** Event category, e.g. 'auth', 'billing', 'startup'. Default: 'client-log' */
+    type: string;
+    /** Epoch milliseconds */
+    timestamp: number;
+    level: LogLevel;
+    message: string;
+    /** Duration in milliseconds (for timed events that aren't span-shaped) */
+    duration?: number;
+    /** Serialized error info (message, type, stack) */
+    error?: {
+        message: string;
+        type?: string;
+        stack?: string;
+    };
+    /** Arbitrary key-value event data */
+    params?: Record<string, JsonValue>;
+}
+export interface TimerItem {
+    /** 16-char hex ID, generated client-side */
+    id: string;
+    /** 32-char hex trace ID, shared by parent + children */
+    trace_id: string;
+    /** ID of the root timer in this trace (for transaction_id on spans) */
+    root_id: string;
+    /** 16-char hex ID of parent timer (absent for root timers) */
+    parent_id?: string;
+    /** Operation name, e.g. 'content-store-startup' */
+    name: string;
+    /** Timer category. Default: 'client-perf' */
+    type: string;
+    /** Start time, epoch milliseconds */
+    timestamp: number;
+    /** Duration in milliseconds */
+    duration: number;
+    outcome: 'success' | 'failure' | 'unknown';
+    context?: {
+        tags?: Record<string, JsonValue>;
+    };
+}
+export interface ClientInfo {
+    /** Application name, e.g. 'duiduidui-app' */
+    name: string;
+    /** Application version */
+    version: string;
+    os: {
+        name: string;
+        version: string;
+    };
+    device: {
+        model?: string;
+        brand?: string;
+        type: string;
+    };
+    runtime: {
+        name: string;
+        version: string;
+    };
+    screen?: {
+        width: number;
+        height: number;
+        pixel_ratio: number;
+    };
+    locale?: string;
+    timezone?: string;
+    device_year_class?: number;
+}
+export interface TimerToken {
+    /** 16-char hex ID for this timer */
+    id: string;
+    /** 32-char hex trace ID (shared across the entire timer tree) */
+    trace_id: string;
+    /** ID of the root timer in this trace */
+    root_id: string;
+    /** Key/name of the operation being timed */
+    key: string;
+}
+export interface LogClientOptions {
+    /** Server endpoint URL for log submission */
+    endpoint: string;
+    /** Returns auth headers (e.g. { Authorization: 'Bearer ...' }) */
+    getAuthHeaders: () => Promise<Record<string, string>> | Record<string, string>;
+    /** Static client/device info, sent once per batch */
+    client: ClientInfo;
+    /** Returns current user ID, if logged in */
+    getUserId?: () => string | undefined;
+    /** Returns current session reference */
+    getSessionRef?: () => string | undefined;
+    /** Returns native device identifier */
+    getDeviceId?: () => string | undefined;
+    /** Flush interval in ms. Default: 5000 */
+    flushIntervalMs?: number;
+    /** Max events buffered before forced flush. Default: 100 */
+    maxBufferSize?: number;
+    /** Max events per HTTP request. Default: 50 */
+    maxChunkSize?: number;
+    /** Max bytes per HTTP request. Default: 524288 (512KB) */
+    maxChunkBytes?: number;
+    /** Persist pending logs (e.g. to AsyncStorage). Called with JSON string. */
+    persistLogs?: (data: string) => Promise<void>;
+    /** Load previously persisted logs. Returns JSON string or null. */
+    loadPersistedLogs?: () => Promise<string | null>;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// ---- JSON value type (any valid JSON) ----
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@redthreadlabs/tracelog-client",
+  "version": "1.3.0",
+  "description": "Lightweight logging client for tracelog — works in React Native and browsers",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "latest"
+  }
+}