edsger-logs 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# edsger-logs
+
+Send product logs to [Edsger](https://edsger.ai) for user behavior analytics and product improvement.
+
+## Installation
+
+```bash
+npm install edsger-logs
+```
+
+## Quick Start (Recommended)
+
+Use `createLogger()` for non-blocking, fire-and-forget logging that never interferes with your product's normal flow:
+
+```ts
+import { createLogger } from 'edsger-logs'
+
+const logger = createLogger({
+  productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+  userId: 'user-uuid',
+  sessionId: 'sess_abc123',
+})
+
+// Fire-and-forget — no await, no try/catch, no this-binding issues
+logger.log('page_view', 'User viewed feature list', { metadata: { page: '/features' } })
+logger.log('button_click', 'Clicked create feature')
+
+// Safe to destructure
+const { log, flush, dispose } = logger
+log('search', 'Searched for auth')
+
+// Create a scoped child logger with different context (immutable)
+const adminLogger = logger.withContext({ userId: 'admin-uuid' })
+adminLogger.log('settings_changed', 'Updated notification preferences')
+
+// On app shutdown
+await flush()
+dispose()
+```
+
+## API
+
+### `createLogger(options)` (Recommended)
+
+Closure-based non-blocking logger. No `this`, no classes, safe to destructure. Buffers logs in memory and flushes to server every 5 seconds or when buffer reaches 50 entries.
+
+```ts
+const logger = createLogger({
+  productId: 'xxx',         // Required
+  userId: 'user-id',        // Optional: default user for all logs
+  sessionId: 'sess-id',     // Optional: default session for all logs
+  endpoint: '...',          // Optional: custom endpoint
+  flushInterval: 5000,      // Optional: flush every N ms (default: 5000)
+  maxBufferSize: 50,        // Optional: auto-flush at N entries (default: 50)
+  onError: (err) => {},     // Optional: error callback (silent by default)
+})
+
+logger.log('event', 'message')              // Non-blocking, never throws
+logger.log('event', 'msg', { metadata })    // With metadata
+logger.log('event', 'msg', { userId })      // Override user per-call
+
+const child = logger.withContext({ sessionId: 'new-sess' })  // Immutable child
+await logger.flush()                        // Manual flush (e.g. on shutdown)
+logger.dispose()                            // Stop timer, release resources
+```
+
+### `sendLog(options)`
+
+Low-level async function. Send a single log entry. Returns `Promise<SendLogResult>`.
+**Note:** This is async and throws on error — use `createLogger()` instead for non-blocking usage.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `productId` | `string` | Yes | Product UUID |
+| `logType` | `string` | Yes | Event type (max 50 chars), e.g. `page_view`, `button_click`, `error` |
+| `message` | `string` | Yes | Human-readable description (max 5000 chars) |
+| `userId` | `string` | No | Authenticated user UUID |
+| `sessionId` | `string` | No | Session identifier to group related events |
+| `metadata` | `object` | No | Structured data for the event |
+
+**Returns:**
+
+```ts
+{ id: string; createdAt: string }
+```
+
+### `sendLogs(options)`
+
+Send multiple log entries in a single request. Returns `Promise<BatchSendLogResult>`.
+
+```ts
+import { sendLogs } from 'edsger-logs'
+
+await sendLogs({
+  logs: [
+    { productId: '...', logType: 'page_view', message: 'Viewed home' },
+    { productId: '...', logType: 'button_click', message: 'Clicked create' },
+  ],
+})
+```
+
+Max 100 logs per batch. Returns `{ count: number }`.
+
+## Error Handling
+
+```ts
+import { sendLog, LogError } from 'edsger-logs'
+
+try {
+  await sendLog({ ... })
+} catch (err) {
+  if (err instanceof LogError) {
+    console.error(err.message, err.statusCode)
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 18 (uses native `fetch`)
+
+## License
+
+ISC

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+import type { SendLogOptions, SendLogResult, BatchSendLogOptions, BatchSendLogResult } from './types.js';
+/**
+ * Send a single product log entry.
+ *
+ * @example
+ * ```ts
+ * import { sendLog } from 'edsger-logs'
+ *
+ * await sendLog({
+ *   productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+ *   logType: 'page_view',
+ *   message: 'User viewed feature list',
+ *   sessionId: 'sess_abc123',
+ *   metadata: { page: '/features', referrer: '/dashboard' },
+ * })
+ * ```
+ */
+export declare function sendLog(options: SendLogOptions, endpoint?: string): Promise<SendLogResult>;
+/**
+ * Send multiple product log entries in a single request.
+ *
+ * @example
+ * ```ts
+ * import { sendLogs } from 'edsger-logs'
+ *
+ * await sendLogs({
+ *   logs: [
+ *     { productId: '...', logType: 'page_view', message: 'Viewed home' },
+ *     { productId: '...', logType: 'button_click', message: 'Clicked create' },
+ *   ],
+ * })
+ * ```
+ */
+export declare function sendLogs(options: BatchSendLogOptions, endpoint?: string): Promise<BatchSendLogResult>;

package/dist/client.js

@@ -0,0 +1,110 @@
+import { LogError } from './types.js';
+const DEFAULT_ENDPOINT = 'https://ktkogvogdaffjmvrewiu.supabase.co/functions/v1/product-logs';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Send a single product log entry.
+ *
+ * @example
+ * ```ts
+ * import { sendLog } from 'edsger-logs'
+ *
+ * await sendLog({
+ *   productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+ *   logType: 'page_view',
+ *   message: 'User viewed feature list',
+ *   sessionId: 'sess_abc123',
+ *   metadata: { page: '/features', referrer: '/dashboard' },
+ * })
+ * ```
+ */
+export async function sendLog(options, endpoint) {
+    validate(options);
+    const res = await fetch(endpoint || DEFAULT_ENDPOINT, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            product_id: options.productId,
+            log_type: options.logType.trim(),
+            message: options.message.trim(),
+            user_id: options.userId || undefined,
+            session_id: options.sessionId || undefined,
+            metadata: options.metadata || {},
+        }),
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        throw new LogError(data.error || 'Failed to send log', res.status);
+    }
+    return {
+        id: data.log.id,
+        createdAt: data.log.created_at,
+    };
+}
+/**
+ * Send multiple product log entries in a single request.
+ *
+ * @example
+ * ```ts
+ * import { sendLogs } from 'edsger-logs'
+ *
+ * await sendLogs({
+ *   logs: [
+ *     { productId: '...', logType: 'page_view', message: 'Viewed home' },
+ *     { productId: '...', logType: 'button_click', message: 'Clicked create' },
+ *   ],
+ * })
+ * ```
+ */
+export async function sendLogs(options, endpoint) {
+    if (!options.logs || options.logs.length === 0) {
+        throw new LogError('logs array is required and must not be empty', 400);
+    }
+    if (options.logs.length > 100) {
+        throw new LogError('Cannot send more than 100 logs at once', 400);
+    }
+    for (const log of options.logs) {
+        validate(log);
+    }
+    const res = await fetch((endpoint || DEFAULT_ENDPOINT) + '/batch', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            logs: options.logs.map((log) => ({
+                product_id: log.productId,
+                log_type: log.logType.trim(),
+                message: log.message.trim(),
+                user_id: log.userId || undefined,
+                session_id: log.sessionId || undefined,
+                metadata: log.metadata || {},
+            })),
+        }),
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        throw new LogError(data.error || 'Failed to send logs', res.status);
+    }
+    return { count: data.count };
+}
+function validate(options) {
+    if (!options.productId) {
+        throw new LogError('productId is required', 400);
+    }
+    if (!UUID_RE.test(options.productId)) {
+        throw new LogError('productId must be a valid UUID', 400);
+    }
+    if (!options.logType?.trim()) {
+        throw new LogError('logType is required', 400);
+    }
+    if (options.logType.length > 50) {
+        throw new LogError('logType must be 50 characters or less', 400);
+    }
+    if (!options.message?.trim()) {
+        throw new LogError('message is required', 400);
+    }
+    if (options.message.length > 5000) {
+        throw new LogError('message must be 5000 characters or less', 400);
+    }
+    if (options.userId && !UUID_RE.test(options.userId)) {
+        throw new LogError('userId must be a valid UUID', 400);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { sendLog, sendLogs } from './client.js';
+export { createLogger } from './logger.js';
+export { LogError, type SendLogOptions, type SendLogResult, type BatchSendLogOptions, type BatchSendLogResult, type LoggerOptions, type LogContext, type Logger, } from './types.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { sendLog, sendLogs } from './client.js';
+export { createLogger } from './logger.js';
+export { LogError, } from './types.js';

package/dist/logger.d.ts

@@ -0,0 +1,27 @@
+import type { LoggerOptions, Logger } from './types.js';
+/**
+ * Create a non-blocking product logger.
+ *
+ * Uses closure-based state — no `this` binding issues, safe to destructure.
+ * Buffers logs in memory and flushes periodically. Never throws, never blocks.
+ *
+ * @example
+ * ```ts
+ * import { createLogger } from 'edsger-logs'
+ *
+ * const logger = createLogger({ productId: 'xxx', userId: 'user-1' })
+ *
+ * // Fire-and-forget — no await, no try/catch
+ * logger.log('page_view', 'Viewed feature list', { metadata: { page: '/features' } })
+ * logger.log('button_click', 'Clicked create')
+ *
+ * // Create a scoped child logger with different context
+ * const sessionLogger = logger.withContext({ sessionId: 'sess_abc' })
+ * sessionLogger.log('search', 'Searched for auth')
+ *
+ * // On shutdown
+ * await logger.flush()
+ * logger.dispose()
+ * ```
+ */
+export declare function createLogger(options: LoggerOptions): Logger;

package/dist/logger.js

@@ -0,0 +1,108 @@
+const DEFAULT_ENDPOINT = 'https://ktkogvogdaffjmvrewiu.supabase.co/functions/v1/product-logs';
+const DEFAULT_FLUSH_INTERVAL = 5_000;
+const DEFAULT_MAX_BUFFER_SIZE = 50;
+const isBrowser = typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function';
+/**
+ * Create a non-blocking product logger.
+ *
+ * Uses closure-based state — no `this` binding issues, safe to destructure.
+ * Buffers logs in memory and flushes periodically. Never throws, never blocks.
+ *
+ * @example
+ * ```ts
+ * import { createLogger } from 'edsger-logs'
+ *
+ * const logger = createLogger({ productId: 'xxx', userId: 'user-1' })
+ *
+ * // Fire-and-forget — no await, no try/catch
+ * logger.log('page_view', 'Viewed feature list', { metadata: { page: '/features' } })
+ * logger.log('button_click', 'Clicked create')
+ *
+ * // Create a scoped child logger with different context
+ * const sessionLogger = logger.withContext({ sessionId: 'sess_abc' })
+ * sessionLogger.log('search', 'Searched for auth')
+ *
+ * // On shutdown
+ * await logger.flush()
+ * logger.dispose()
+ * ```
+ */
+export function createLogger(options) {
+    const productId = options.productId;
+    const endpoint = options.endpoint || DEFAULT_ENDPOINT;
+    const maxBufferSize = options.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE;
+    const onError = options.onError;
+    // Shared mutable buffer (shared across parent + child loggers)
+    const buffer = [];
+    let flushing = false;
+    const timer = setInterval(() => {
+        flush().catch(() => { });
+    }, options.flushInterval ?? DEFAULT_FLUSH_INTERVAL);
+    if (typeof timer === 'object' && 'unref' in timer) {
+        timer.unref();
+    }
+    function flush() {
+        if (buffer.length === 0 || flushing)
+            return Promise.resolve();
+        flushing = true;
+        // Snapshot and clear — avoids concurrent mutation
+        const batch = buffer.splice(0);
+        const body = JSON.stringify({ logs: batch });
+        if (isBrowser) {
+            const blob = new Blob([body], { type: 'application/json' });
+            const queued = navigator.sendBeacon(endpoint + '/batch', blob);
+            if (!queued) {
+                onError?.(new Error('sendBeacon failed to queue'));
+            }
+            flushing = false;
+            return Promise.resolve();
+        }
+        // Node.js fallback
+        return fetch(endpoint + '/batch', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+        })
+            .then(() => { })
+            .catch((error) => {
+            onError?.(error instanceof Error ? error : new Error(String(error)));
+        })
+            .finally(() => {
+            flushing = false;
+        });
+    }
+    // Flush remaining logs when the page is about to close (browser only)
+    const beforeUnloadHandler = isBrowser
+        ? () => { flush().catch(() => { }); }
+        : undefined;
+    if (beforeUnloadHandler) {
+        addEventListener('beforeunload', beforeUnloadHandler);
+    }
+    function dispose() {
+        clearInterval(timer);
+        if (beforeUnloadHandler) {
+            removeEventListener('beforeunload', beforeUnloadHandler);
+        }
+    }
+    // Factory for creating a logger bound to specific defaults
+    function makeLogger(defaultUserId, defaultSessionId) {
+        const log = (logType, message, context) => {
+            if (!logType || !message)
+                return;
+            buffer.push({
+                product_id: productId,
+                log_type: logType.slice(0, 50),
+                message: message.slice(0, 5000),
+                user_id: context?.userId ?? defaultUserId,
+                session_id: context?.sessionId ?? defaultSessionId,
+                metadata: context?.metadata ?? {},
+            });
+            if (buffer.length >= maxBufferSize) {
+                flush().catch(() => { });
+            }
+        };
+        const withContext = (ctx) => makeLogger(ctx.userId ?? defaultUserId, ctx.sessionId ?? defaultSessionId);
+        return { log, flush, withContext, dispose };
+    }
+    return makeLogger(options.userId, options.sessionId);
+}

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+export interface SendLogOptions {
+    /** Product ID (UUID) */
+    productId: string;
+    /** Log type, e.g. "page_view", "button_click", "error", "feature_used" */
+    logType: string;
+    /** Human-readable description of the event */
+    message: string;
+    /** Optional user ID (UUID) for authenticated users */
+    userId?: string;
+    /** Optional session ID to group related events */
+    sessionId?: string;
+    /** Optional structured metadata for the event */
+    metadata?: Record<string, unknown>;
+}
+export interface SendLogResult {
+    id: string;
+    createdAt: string;
+}
+export interface BatchSendLogOptions {
+    /** Array of log entries to send */
+    logs: SendLogOptions[];
+}
+export interface BatchSendLogResult {
+    count: number;
+}
+export interface LoggerOptions {
+    /** Product ID (UUID) - required */
+    productId: string;
+    /** Default user ID applied to all logs (optional, overridden per-call) */
+    userId?: string;
+    /** Default session ID applied to all logs (optional, overridden per-call) */
+    sessionId?: string;
+    /** Custom endpoint URL (optional, for self-hosted or testing) */
+    endpoint?: string;
+    /** Flush interval in ms (default: 5000) */
+    flushInterval?: number;
+    /** Max buffer size before auto-flush (default: 50) */
+    maxBufferSize?: number;
+    /** Error callback - called silently, never throws (optional) */
+    onError?: (error: Error) => void;
+}
+export interface LogContext {
+    /** Override user ID for this log entry */
+    userId?: string;
+    /** Override session ID for this log entry */
+    sessionId?: string;
+    /** Structured metadata for the event */
+    metadata?: Record<string, unknown>;
+}
+export interface Logger {
+    /** Log an event. Non-blocking, never throws. */
+    log: (logType: string, message: string, context?: LogContext) => void;
+    /** Flush buffered logs to the server. */
+    flush: () => Promise<void>;
+    /** Create a child logger with additional default context. */
+    withContext: (context: Partial<Pick<LoggerOptions, 'userId' | 'sessionId'>>) => Logger;
+    /** Stop the flush timer and release resources. */
+    dispose: () => void;
+}
+export declare class LogError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+export class LogError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'LogError';
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "edsger-logs",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "edsger",
+    "logs",
+    "product-logs",
+    "analytics"
+  ],
+  "author": "",
+  "license": "ISC",
+  "description": "Send product logs to Edsger for user behavior analytics",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stevenzg/edsger.git",
+    "directory": "packages/logs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}