@adv-re/segment-wrapper 4.36.0-beta.0

package/README.md

@@ -0,0 +1,240 @@
+# @adv-re/segment-wrapper
+
+Modern TypeScript abstraction layer on top of the Segment Analytics library with built-in support for Google Analytics 4, Adobe Analytics, TCF compliance, and consent management.
+
+## Features
+
+- ✨ **TypeScript Support** - Full type safety and IntelliSense
+- 🔒 **TCF/GDPR Compliance** - Built-in Transparency & Consent Framework support
+- 📊 **Google Analytics 4** - Native GA4 integration with consent mode
+- 🎯 **Adobe Analytics** - Adobe Visitor API integration
+- 🔌 **Middleware System** - Extensible source and destination middlewares
+- 🆔 **Universal ID** - User identification across domains
+- 📦 **Multiple Formats** - ESM, CommonJS, and UMD builds
+- 🧪 **Well Tested** - 203 tests with 80%+ coverage
+
+## Installation
+
+```bash
+npm install @adv-re/segment-wrapper
+```
+
+## Quick Start
+
+### Basic Usage (ESM/TypeScript)
+
+```typescript
+import analytics from '@adv-re/segment-wrapper'
+import {initConfig} from '@adv-re/segment-wrapper'
+
+// Initialize configuration
+initConfig({
+  segmentKey: 'your-segment-write-key',
+  googleAnalyticsMeasurementId: 'G-XXXXXXXXXX',
+  googleAnalyticsConsentManagement: true
+})
+
+// Track events
+await analytics.track('Button Clicked', {
+  buttonName: 'Sign Up',
+  location: 'Homepage'
+})
+
+// Track page views
+await analytics.page('Homepage', {
+  title: 'Welcome to Our Site'
+})
+
+// Identify users
+await analytics.identify('user-123', {
+  email: 'user@example.com',
+  plan: 'premium'
+})
+```
+
+### UMD Usage (Browser)
+
+```html
+<script src="https://cdn.segment.com/analytics.js/v1/YOUR_WRITE_KEY/analytics.min.js"></script>
+<script src="/path/to/umd/index.global.js"></script>
+
+<script>
+  // Access via window.sui.analytics
+  window.sui.analytics.track('Page Viewed', {
+    page: 'home'
+  })
+</script>
+```
+
+## Configuration
+
+```typescript
+import {initConfig} from '@adv-re/segment-wrapper'
+
+initConfig({
+  // Segment
+  segmentKey: 'your-segment-write-key',
+  
+  // Google Analytics 4
+  googleAnalyticsMeasurementId: 'G-XXXXXXXXXX',
+  googleAnalyticsConsentManagement: true,
+  googleAnalyticsConfig: {
+    // Custom GA4 config
+  },
+  
+  // Adobe Analytics
+  adobeVisitorId: 'YOUR_ADOBE_ORG_ID@AdobeOrg',
+  
+  // TCF/GDPR
+  enableTcf: true,
+  
+  // Universal ID
+  universalId: 'user-universal-id',
+  userEmail: 'user@example.com',
+  
+  // Middlewares
+  experimentalPageDataMiddleware: false,
+  
+  // Other
+  defaultProperties: {
+    platform: 'web',
+    app: 'my-app'
+  },
+  userIdPrefix: 'usr_'
+})
+```
+
+See [Configuration Guide](./docs/configuration.md) for all available options.
+
+## API Reference
+
+### Core Methods
+
+- `analytics.track(event, properties?, context?, callback?)` - Track custom events
+- `analytics.page(name?, properties?, context?, callback?)` - Track page views
+- `analytics.identify(userId, traits?, options?, callback?)` - Identify users
+- `analytics.reset()` - Reset user identification
+
+### Utilities
+
+- `getConfig(key)` - Get configuration value
+- `setConfig(key, value)` - Set configuration value
+- `clearConfig()` - Clear all configuration
+- `getUniversalId()` - Get current Universal ID
+- `getAdobeMCVisitorID()` - Get Adobe Marketing Cloud Visitor ID
+- `getAdobeVisitorData()` - Get Adobe Visitor API data
+
+See [API Reference](./docs/api-reference.md) for detailed documentation.
+
+## Advanced Features
+
+### Middleware System
+
+The segment-wrapper includes a powerful middleware system that allows you to modify tracking data before it's sent:
+
+```typescript
+// Middlewares are automatically registered on initialization
+// They enrich events with:
+// - User traits (anonymous ID, user ID)
+// - Campaign context (UTM parameters, STC tracking)
+// - Page referrer information
+// - Screen dimensions
+// - Default context properties
+```
+
+See [Middleware Documentation](./docs/middlewares.md) for more details.
+
+### TCF/GDPR Compliance
+
+Built-in support for Transparency & Consent Framework (TCF) v2:
+
+```typescript
+import {getGdprPrivacyValue, checkAnalyticsGdprIsAccepted} from '@adv-re/segment-wrapper'
+
+// Get current GDPR consent state
+const gdprValue = await getGdprPrivacyValue()
+// { analytics: 'accepted', advertising: 'declined' }
+
+// Check if analytics tracking is allowed
+const canTrack = checkAnalyticsGdprIsAccepted(gdprValue)
+```
+
+Events are automatically blocked or modified based on user consent.
+
+See [TCF Documentation](./docs/tcf-compliance.md) for more details.
+
+### Google Analytics 4 Integration
+
+Native GA4 integration with automatic consent mode:
+
+```typescript
+initConfig({
+  googleAnalyticsMeasurementId: 'G-XXXXXXXXXX',
+  googleAnalyticsConsentManagement: true,
+  googleAnalyticsConfig: {
+    send_page_view: false,
+    // Additional GA4 config options
+  }
+})
+```
+
+Features:
+- Automatic consent mode updates based on TCF
+- Session and client ID tracking
+- Campaign parameter forwarding
+- Custom event tracking
+
+## Migration from @s-ui/segment-wrapper
+
+See [Migration Guide](./docs/migration-guide.md) for step-by-step instructions on migrating from the legacy `@s-ui/segment-wrapper` package.
+
+Key changes:
+- Package name: `@s-ui/segment-wrapper` → `@adv-re/segment-wrapper`
+- Full TypeScript support with type definitions
+- Modern build system (tsup instead of sui-bundler)
+- Improved tree-shaking and bundle size
+
+## Browser Support
+
+- Chrome/Edge (last 2 versions)
+- Firefox (last 2 versions)
+- Safari (last 2 versions)
+- iOS Safari (last 2 versions)
+
+## Bundle Size
+
+- ESM: ~34KB (minified)
+- CommonJS: ~36KB (minified)
+- UMD: ~15KB (minified)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Build UMD bundle
+npm run build:umd
+
+# Lint
+npm run lint
+```
+
+## Documentation
+
+- [Configuration Guide](./docs/configuration.md)
+- [API Reference](./docs/api-reference.md)
+- [Middleware System](./docs/middlewares.md)
+- [TCF Compliance](./docs/tcf-compliance.md)
+- [Migration Guide](./docs/migration-guide.md)
+- [Examples](./docs/examples.md)
+
+## License
+
+ISC