# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

TD-JS-SDK is a browser JavaScript library for collecting event data and sending it to Treasure Data. It's designed with privacy-first principles, featuring GDPR compliance, an extensible plugin architecture, and an async loading pattern for zero-blocking performance.

## Common Development Commands

### Building the SDK
```bash
# Full build (includes dev, prod, and loader)
npm run build
# or
./bin/build.sh

# Individual builds
npm run build-dev     # Development version (dist/td.js)
npm run build-prod    # Minified version (dist/td.min.js)
npm run build-loader  # Async loader snippet (dist/loader.min.js)
```

### Testing
```bash
# Run all tests (includes linting and build)
npm test

# Run tests locally in browsers
npm run test-local

# Run only linting
npx standard
```

### Build Configuration
The build script supports customization via CLI flags:
```bash
./bin/build.sh --GLOBAL=CustomTreasure --FILENAME=custom --HOST=custom.host.com
```

## Architecture Overview

### Core Module Structure

**Main Entry Point**: `lib/index.js`
- Imports Treasure class and processes async loader clients

**Core Class**: `lib/treasure.js`
- Main SDK class with plugin system integration
- All plugin methods are mixed into `Treasure.prototype`

**Key Supporting Modules**:
- `lib/configurator.js` - Three-tier configuration system ($global → table → record)
- `lib/record.js` - Event recording with privacy controls (Anonymous/Signed modes)
- `lib/loadClients.js` - Async loader client replay system

### Plugin Architecture

The SDK uses an **extensible plugin system** where all features are implemented as plugins:

**Plugin Location**: `lib/plugins/`

**Plugin Structure**:
```javascript
module.exports = {
  configure: function(config) { /* initialization */ },
  methodName: function() { /* feature implementation */ }
}
```

**Available Plugins**:
- `track.js` - Core tracking functionality with automatic browser data collection
- `clicks.js` - Automatic click tracking with DOM event listeners
- `globalid.js` - Cross-domain user identification
- `servicesidecookie.js` - ITP 1.2 compliant tracking
- `consentmanager.js` - GDPR compliance features
- `personalization.js` - User segment and personalization APIs
- `conversionapi.js` - Conversion tracking support
- `utmtracking.js` - UTM parameter collection

**Plugin Registration**: Plugins are automatically registered in `treasure.js` and their methods are mixed into the Treasure prototype.

### Privacy-First Design

The SDK operates in two modes:
- **Anonymous Mode** (default): Strips PII (`td_ip`, `td_client_id`, `td_global_id`)
- **Signed Mode**: Includes PII for authenticated users

Key privacy methods: `blockEvents()`, `setAnonymousMode()`, `setSignedMode()`, `resetUUID()`

### Async Loading Pattern

1. **Loader Stub** (`src/loader.js`): Creates fake Treasure object, buffers method calls
2. **Client Replay** (`lib/loadClients.js`): Replays buffered calls when real SDK loads
3. **Zero Blocking**: Page can use SDK immediately, gets upgraded transparently

## Development Patterns

### Adding a New Plugin

1. Create `lib/plugins/yourfeature.js`:
```javascript
module.exports = {
  configure: function(config) {
    // Plugin initialization
  },

  yourMethod: function() {
    // Feature implementation
    // Access config via: this.config
    // Access utilities via: this._
  }
}
```

2. Register in `lib/treasure.js`:
```javascript
var YourFeature = require('./plugins/yourfeature')
// Add to Treasure.Plugins object
```

3. Add tests in `test/treasure.yourfeature.spec.js`

### Configuration System

Three-tier property application:
1. `$global` properties (all tables)
2. Table-specific properties
3. Record properties (method arguments)

Use `treasure.set()` to set defaults:
```javascript
treasure.set('$global', 'key', 'value')  // All tables
treasure.set('table', 'key', 'value')    // Specific table
```

### HTTP Transport

The SDK uses a fallback HTTP client pattern in `lib/utils/xhr.js`:
- **Fetch API first** (with keepalive support)
- **XMLHttpRequest fallback** for older browsers
- **Timeout handling** with AbortController or Promise.race

### Browser Compatibility

Targets browsers from last 2.5 years via Browserslist:
- Chrome, Edge, Safari, Firefox
- Android Chrome/Firefox, iOS Safari
- No IE support from v1.5.2+

## Testing Structure

**Framework**: Karma + Mocha + Expect.js
**Browsers**: Chrome, Firefox, Safari (via Karma)

**Test Organization**:
- `test/treasure.*.spec.js` - Feature-specific tests
- `test/e2e/` - End-to-end tests
- Tests use `simple-mock` for mocking
- Configuration reset between tests

**Run Single Test**:
```bash
npx karma start --browsers Chrome --grep "test description"
```

## Build System Details

**Tool**: Rollup with plugins:
- Node resolution + CommonJS support
- Babel transpilation (browserslist targeting)
- Terser minification (production only)

**Template System**: `lib/config.template.js` → `lib/config.js`
- Replaces `@VERSION`, `@GLOBAL`, `@HOST` etc. during build

**Outputs**:
- `dist/td.js` (~228KB) - Development build
- `dist/td.min.js` (~60KB) - Production build
- `dist/loader.min.js` - Async loader snippet

## Key File Locations

**Core Logic**:
- `lib/treasure.js` - Main SDK class
- `lib/record.js` - Privacy controls and event processing
- `lib/configurator.js` - Configuration management

**Utilities**:
- `lib/utils/xhr.js` - HTTP client with Fetch/XHR fallback
- `lib/utils/misc.js` - `invariant`, `fetchWithTimeout`, helpers
- `lib/utils/element.js` - DOM utilities for click tracking

**Build**:
- `bin/build.sh` - Build orchestration with template substitution
- `rollup-*.config.js` - Rollup configurations
- `karma.conf.js` - Test configuration

**Documentation**:
- `README.md` - User-facing API documentation
- `*.md` files - Feature-specific documentation (ConsentManager, Personalization, etc.)

## Privacy and GDPR Compliance

The SDK is designed with privacy compliance built-in:
- Default Anonymous mode strips PII
- Event blocking capabilities with persistence
- UUID reset functionality
- Consent management integration
- Server-side cookie support for ITP compliance

When modifying privacy-related code, always test both Anonymous and Signed modes, and ensure event blocking works correctly.