npm package: @signal-js/core
Description: Core utilities for Signal SDK
Latest version: 1.0.6

# @signal-js/core

Core utilities and shared functionality for Signal SDK.

## Installation

```bash
npm install @signal-js/core
# or
pnpm add @signal-js/core
# or
yarn add @signal-js/core
```

## Features

- **Environment Detection**: Safe browser/Node.js detection
- **Storage Layer**: Cookie, localStorage, sessionStorage with fallback chain
- **Session Management**: Configurable timeouts, UUIDv7, activity tracking
- **Compression**: Gzip compression using fflate
- **Logger**: Debug-aware logging with scoped loggers
- **Utilities**: Type checking, string manipulation, async helpers

## Usage

### Session Management

```typescript
import { createSessionManager, SessionIdManager } from '@signal-js/core';

const session = createSessionManager({
  sessionIdleTimeoutSeconds: 30 * 60, // 30 minutes
  maxSessionLengthSeconds: 24 * 60 * 60, // 24 hours
});

// Get session ID (creates new one if expired)
const sessionId = session.getSessionId();

// Listen for session changes
session.onSessionId((sessionId, windowId, reason) => {
  console.log('Session changed:', sessionId, reason);
});

// Bootstrap with existing session
session.bootstrap(existingSessionId);
```

### Storage

```typescript
import { StorageWrapper, localStore, cookieStore, hybridStore } from '@signal-js/core';

// Use wrapper with prefix
const storage = new StorageWrapper('local', 'myapp');
storage.setJSON('user', { name: 'John' });
const user = storage.getJSON('user');

// Use cookie store directly
cookieStore._set('session_id', 'abc123', 365, true, true);

// Hybrid store (localStorage + cookie for critical data)
hybridStore._set('data', { session_id: 'abc', other: 'value' });
```

### Compression

```typescript
import { gzipCompress, isGzipSupported } from '@signal-js/core';

if (isGzipSupported()) {
  const compressed = gzipCompress(JSON.stringify(data));
  // Send with Content-Encoding: gzip
}
```

### UUID Generation

```typescript
import { uuidv7, generateSessionId, uuid7ToTimestampMs } from '@signal-js/core';

const uuid = uuidv7(); // Time-sortable UUID
const sessionId = generateSessionId(); // s_<timestamp>_<random>

// Extract timestamp from UUIDv7
const timestamp = uuid7ToTimestampMs(uuid);
```

### Logging

```typescript
import { createLogger, setDebug } from '@signal-js/core';

setDebug(true); // Enable debug logging

const logger = createLogger('[MyComponent]');
logger.info('Something happened');
logger.error('Error occurred', error);
```

## API Reference

### Environment

| Function | Description |
|----------|-------------|
| `isBrowser()` | Check if running in browser |
| `isNode()` | Check if running in Node.js |
| `hasDocument()` | Check if document is available |
| `hasLocalStorage()` | Check if localStorage works |
| `now()` | Current timestamp in ms |
| `isoTimestamp()` | Current ISO timestamp string |

### Storage

| Export | Description |
|--------|-------------|
| `localStore` | localStorage wrapper |
| `sessionStore` | sessionStorage wrapper |
| `cookieStore` | Cookie store with subdomain support |
| `memoryStore` | In-memory fallback store |
| `hybridStore` | localStorage + cookie for critical keys |
| `StorageWrapper` | Class with prefix support |

### Session

| Export | Description |
|--------|-------------|
| `SessionIdManager` | Full session management class |
| `createSessionManager()` | Factory function |

### Utilities

| Function | Description |
|----------|-------------|
| `safeStringify()` | JSON stringify with circular reference handling |
| `redactSensitiveData()` | Redact passwords, tokens, etc. |
| `truncate()` | Truncate strings with suffix |
| `retriable()` | Retry async operations |
| `clampToRange()` | Clamp numbers to range |

## License

MIT