@suucha/core

Platform-agnostic core abstractions for the Suucha Web SDK. Defines reporter / interceptor / logger / storage / ad-manager interfaces and exposes the suucha singleton.

This package has no browser or Node.js dependencies and can be reused by any platform (Web, React Native, mini-program).

Install

pnpm add @suucha/core
# or
npm install @suucha/core

Quick Start

import { suucha, LogLevel } from '@suucha/core';

// Register a reporter (third-party implementation)
class ConsoleReporter {
  readonly name = 'console';
  async logEvent(name: string, params: Record<string, any>) {
    console.log('[event]', name, params);
  }
}

suucha.addReporter(new ConsoleReporter());

// Log events — anonymous_id is auto-attached
suucha.log('page_view');
suucha.log('add_to_cart', { item_id: 'sku_123', value: 99.9 });

// Identify logged-in user — user_id is auto-attached on subsequent events
suucha.identify('user_456');

Key Concepts

Reporters

Implement ILogEventReporter and register via suucha.addReporter(...). Each reporter represents one third-party service (GA4, Sensors, etc.).

Interceptors

• Event interceptors (ILogEventIntercept) can produce new events (e.g., event counting).
• Parameter interceptors (ILogEventParameterIntercept) can modify event params (e.g., attribution, identity).

Built-in:

• IdentityIntercept — auto-attached, adds anonymous_id and user_id
• EventCounterIntercept — count events, emit event_NNN at configured counts

Region Routing

For domestic/overseas reporter switching:

suucha.region.router((ctx) => {
  if (ctx.host.endsWith('.cn')) return 'cn';
  return 'global';
});

suucha.region.reporters({
  cn:     [/* SensorsReporter */],
  global: [/* GA4Reporter */],
});

Consent (Privacy)

GDPR / PIPL compliance:

suucha.setConsent(false);  // events buffer in memory
// ... user grants consent ...
suucha.setConsent(true);   // buffered events flush to reporters

API

See docs/api-draft.md for the full v1 API contract.

License

MIT © Suucha Studio