Timberlogs TypeScript SDK

A lightweight, flexible TypeScript SDK for structured logging with Timberlogs.

Installation

``bash
npm install timberlogs-client


or

pnpm add timberlogs-client

or

yarn add timberlogs-client
`

Quick Start

`typescript
import { createTimberlogs } from "timberlogs-client";

const logger = createTimberlogs({
source: "my-app",
environment: "production",
apiKey: "your-api-key",
});

// Log messages at different levels
logger.debug("Debug information", { details: "..." });
logger.info("User logged in", { userId: "123" });
logger.warn("Rate limit approaching", { current: 95, limit: 100 });
logger.error("Payment failed", new Error("Insufficient funds"));
`

Features

- Multiple log levels: debug, info, warn, error
- Structured logging: Attach arbitrary data to logs
- Tags support: Categorize logs with tags
- Automatic batching: Efficiently send logs in batches
- Retry with backoff: Automatic retries on failure
- User/Session tracking: Track logs by user and session
- Flexible transport: HTTP or custom backend integration

Configuration

`typescript
const logger = createTimberlogs({
// Required
source: "my-app", // Your application name
environment: "production", // development | staging | production
apiKey: "your-api-key", // Your Timberlogs API key

// Optional
version: "1.0.0", // App version
userId: "user-123", // Default user ID
sessionId: "session-abc", // Default session ID
batchSize: 10, // Logs to batch before sending (default: 10)
flushInterval: 5000, // Auto-flush interval in ms (default: 5000)
minLevel: "debug", // Minimum log level (default: debug)

// Error handling
onError: (error) => console.error("Logging error:", error),

// Retry configuration
retry: {
maxRetries: 3,
initialDelayMs: 1000,
maxDelayMs: 30000,
},
});
`

Usage

$3

`typescript
logger.debug("Debug message");
logger.info("Info message", { key: "value" });
logger.warn("Warning message");
logger.error("Error message", new Error("Something went wrong"));
`

$3

`typescript
logger.info("User action", { action: "click" }, { tags: ["analytics", "ui"] });
logger.error("Auth failed", error, { tags: ["auth", "security"] });

// Or using the log method
logger.log({
level: "info",
message: "Feature enabled",
tags: ["feature-flag", "experiment-a"],
});
`

$3

`typescript
// Set for all subsequent logs
logger.setUserId("user-123");
logger.setSessionId("session-abc");

// Now all logs include these IDs
logger.info("Action performed"); // Includes userId and sessionId

// Chainable
logger
.setUserId("user-456")
.setSessionId("session-xyz")
.info("Logged in");
`

$3

`typescript
// Force send all queued logs immediately
await logger.flush();

// Disconnect and flush before shutdown
await logger.disconnect();
`

$3

`typescript
const logger = createTimberlogs({
source: "my-app",
environment: "production",
});

// Connect to your own backend functions
logger.connect({
createLog: async (args) => {
// Your implementation
},
createBatchLogs: async (args) => {
// Your implementation
},
});
`

API Reference

$3

Creates a new Timberlogs client instance.

$3

#### Methods

| Method | Description |
|--------|-------------|
| debug(message, data?, options?) | Log a debug message |
| info(message, data?, options?) | Log an info message |
| warn(message, data?, options?) | Log a warning message |
| error(message, error?, options?) | Log an error message |
| log(entry) | Log with full control over entry |
| setUserId(userId) | Set user ID for subsequent logs |
| setSessionId(sessionId) | Set session ID for subsequent logs |
| flush() | Immediately send all queued logs |
| disconnect() | Flush and stop the client |
| connect(mutations) | Connect to custom backend |

$3

`typescript
type LogLevel = "debug" | "info" | "warn" | "error";
type Environment = "development" | "staging" | "production";

interface LogEntry {
level: LogLevel;
message: string;
data?: Record;
userId?: string;
sessionId?: string;
requestId?: string;
errorName?: string;
errorStack?: string;
tags?: string[];
}
``

License

MIT