@cherrydotfun/collector-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,225 @@
+/** Supported event types. */
+type EventType = 'error' | 'log' | 'analytics';
+/** Log severity levels accepted by the backend. */
+type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug';
+/** Well-known analytics event names (extensible with any string). */
+type AnalyticsLevel = 'screen_view' | 'button_click' | 'feature_usage' | string;
+/** Configuration options for {@link CollectorClient}. */
+interface CollectorConfig {
+    /** Base URL of the Collector backend (e.g. `https://collector.cherry.fun`). */
+    baseUrl: string;
+    /** Project API key obtained from the admin panel. */
+    apiKey: string;
+    /** Client platform identifier (e.g. `ios`, `android`, `web`, `server`). */
+    platform?: string;
+    /** Application version string (e.g. `2.1.0`). */
+    version?: string;
+    /** Number of events per batch (default: 10). */
+    batchSize?: number;
+    /** Interval in ms between automatic batch flushes (default: 5000). */
+    flushIntervalMs?: number;
+    /** Interval in seconds between config refreshes from server (default: 300). */
+    configRefreshSec?: number;
+    /** Enable debug logging to `console.debug` (default: false). */
+    debug?: boolean;
+    /**
+     * Called when a network or API error occurs.
+     * @param error  The error that occurred.
+     * @param context  Where the error happened (e.g. `'sendBatch'`, `'metric'`, `'refreshConfig'`).
+     */
+    onError?: (error: Error, context: string) => void;
+}
+/** Event payload sent to the backend. */
+interface CollectorEvent {
+    type: EventType;
+    /** Severity level. Required for `error` and `log` types; optional for `analytics`. */
+    level?: LogLevel;
+    /** Arbitrary event name (e.g. `screen_view`, `button_click`). Used primarily for analytics. */
+    event?: string;
+    /** Human-readable event message. */
+    message: string;
+    /** Arbitrary key-value parameters attached to the event. */
+    params?: Record<string, unknown>;
+    /** Stack trace information (for error events). */
+    stackTrace?: {
+        frames?: unknown[];
+        raw?: string;
+    };
+    /** Logical module that produced the event (e.g. `messaging`, `websocket`). */
+    module?: string;
+    /** Unique device identifier. */
+    deviceId?: string;
+    /** Client platform (e.g. `ios`, `android`). */
+    platform?: string;
+    /** Application version. */
+    version?: string;
+    /** User identifier. */
+    userId?: string;
+    /** Session identifier. */
+    sessionId?: string;
+    /** ISO-8601 timestamp. Defaults to current time if omitted. */
+    timestamp?: string;
+}
+/** Response from `GET /api/config`. */
+interface ConfigResponse {
+    projectId: string;
+    disabled: string[];
+    sampleRates: Record<string, number>;
+    refreshIntervalSec: number;
+}
+/** Response from `POST /api/collect` (single event). */
+interface IngestResponse {
+    ok: boolean;
+    id?: string;
+    error?: string;
+    pattern?: string;
+}
+/** Response from `POST /api/collect/batch`. */
+interface BatchIngestResponse {
+    ok: boolean;
+    accepted: number;
+    rejected: number;
+    errors: Array<{
+        index: number;
+        reason: string;
+    }>;
+}
+/** A single metric key-value pair for batch operations. */
+interface MetricOp {
+    /** Metric key (e.g. `ws_connections`, `active_rooms`). */
+    key: string;
+    /** Numeric value to set. */
+    value: number;
+}
+/** SDK telemetry counters returned by {@link CollectorClient.getStats}. */
+interface CollectorStats {
+    /** Number of events successfully sent to the backend. */
+    sent: number;
+    /** Number of events dropped due to disabled filters. */
+    dropped: number;
+    /** Number of events that failed to send (network/API errors). */
+    failed: number;
+    /** Current number of events waiting in the batch queue. */
+    queueSize: number;
+}
+
+declare class CollectorClient {
+    private config;
+    private queue;
+    private disabledPatterns;
+    private configRefreshTimer;
+    private initialized;
+    private _lastConfig;
+    private _dropped;
+    private _userId;
+    private _sessionId;
+    private _module;
+    private _deviceId;
+    constructor(config: CollectorConfig);
+    /**
+     * Initialize the client: fetches filter configuration from the server
+     * and starts the periodic config refresh timer.
+     * Must be called before sending events.
+     */
+    init(): Promise<void>;
+    /**
+     * Flush all queued events to the server immediately.
+     * Returns when the send completes (or fails silently).
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop all timers and flush remaining events.
+     * Call before application exit or when the client is no longer needed.
+     */
+    destroy(): void;
+    /** Set the user ID attached to all subsequent events. */
+    setUser(userId: string): void;
+    /** Set the session ID attached to all subsequent events. */
+    setSession(sessionId: string): void;
+    /** Set the default module name attached to all subsequent events. */
+    setModule(module: string): void;
+    /** Set the device ID attached to all subsequent events. */
+    setDevice(deviceId: string): void;
+    /**
+     * Send an error event.
+     * @param message  Error description.
+     * @param params   Optional parameters. The special `stackTrace` key is extracted
+     *                 and sent as the structured `stackTrace.raw` field.
+     */
+    error(message: string, params?: Record<string, unknown> & {
+        stackTrace?: string;
+    }): void;
+    /**
+     * Send a log event with an explicit level.
+     * @param level   Severity: `fatal`, `error`, `warn`, `info`, or `debug`.
+     * @param message Log message.
+     * @param params  Optional key-value parameters.
+     */
+    log(level: LogLevel, message: string, params?: Record<string, unknown>): void;
+    /** Shorthand for `log('fatal', message, params)`. */
+    fatal(message: string, params?: Record<string, unknown>): void;
+    /** Shorthand for `log('warn', message, params)`. */
+    warn(message: string, params?: Record<string, unknown>): void;
+    /** Shorthand for `log('info', message, params)`. */
+    info(message: string, params?: Record<string, unknown>): void;
+    /** Shorthand for `log('debug', message, params)`. */
+    debug(message: string, params?: Record<string, unknown>): void;
+    /**
+     * Send an analytics event.
+     * @param event   Event name (e.g. `screen_view`, `button_click`).
+     * @param message Human-readable description (e.g. screen name or action label).
+     * @param params  Optional key-value parameters.
+     */
+    analytics(event: string, message: string, params?: Record<string, unknown>): void;
+    /**
+     * Set a single metric value. Sent immediately (not batched).
+     * @param key   Metric key (e.g. `ws_connections`).
+     * @param value Numeric value.
+     */
+    metric(key: string, value: number): Promise<void>;
+    /**
+     * Set multiple metric values in one request. Sent immediately (not batched).
+     * Backend accepts up to 100 operations per call.
+     * @param ops Array of `{ key, value }` pairs.
+     */
+    metricBatch(ops: MetricOp[]): Promise<void>;
+    /**
+     * Send a single event immediately via `POST /api/collect`, bypassing the batch queue.
+     * Useful for critical events that must not be delayed.
+     *
+     * The event is enriched with context (userId, sessionId, platform, etc.)
+     * and filtered against disabled patterns, same as queued events.
+     *
+     * @param event Partial event data. `type` and `message` are required.
+     */
+    send(event: Partial<CollectorEvent> & {
+        type: CollectorEvent['type'];
+        message: string;
+    }): Promise<void>;
+    /**
+     * Force-refresh the filter configuration from the server.
+     * Normally called automatically on the configured interval.
+     */
+    refreshConfig(): Promise<void>;
+    /**
+     * Returns the last successfully fetched server configuration,
+     * or `null` if no config has been loaded yet.
+     */
+    getConfig(): ConfigResponse | null;
+    /**
+     * Returns SDK telemetry counters: events sent, dropped (filtered), failed,
+     * and current queue size.
+     */
+    getStats(): CollectorStats;
+    /** Whether {@link init} has been called and completed successfully. */
+    get isInitialized(): boolean;
+    private buildEvent;
+    private enqueue;
+    private isDisabled;
+    private sendBatch;
+    private doFetch;
+    private handleError;
+    private log_debug;
+}
+
+export { type AnalyticsLevel, type BatchIngestResponse, CollectorClient, type CollectorConfig, type CollectorEvent, type CollectorStats, type ConfigResponse, type EventType, type IngestResponse, type LogLevel, type MetricOp };

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+/** Supported event types. */
+type EventType = 'error' | 'log' | 'analytics';
+/** Log severity levels accepted by the backend. */
+type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug';
+/** Well-known analytics event names (extensible with any string). */
+type AnalyticsLevel = 'screen_view' | 'button_click' | 'feature_usage' | string;
+/** Configuration options for {@link CollectorClient}. */
+interface CollectorConfig {
+    /** Base URL of the Collector backend (e.g. `https://collector.cherry.fun`). */
+    baseUrl: string;
+    /** Project API key obtained from the admin panel. */
+    apiKey: string;
+    /** Client platform identifier (e.g. `ios`, `android`, `web`, `server`). */
+    platform?: string;
+    /** Application version string (e.g. `2.1.0`). */
+    version?: string;
+    /** Number of events per batch (default: 10). */
+    batchSize?: number;
+    /** Interval in ms between automatic batch flushes (default: 5000). */
+    flushIntervalMs?: number;
+    /** Interval in seconds between config refreshes from server (default: 300). */
+    configRefreshSec?: number;
+    /** Enable debug logging to `console.debug` (default: false). */
+    debug?: boolean;
+    /**
+     * Called when a network or API error occurs.
+     * @param error  The error that occurred.
+     * @param context  Where the error happened (e.g. `'sendBatch'`, `'metric'`, `'refreshConfig'`).
+     */
+    onError?: (error: Error, context: string) => void;
+}
+/** Event payload sent to the backend. */
+interface CollectorEvent {
+    type: EventType;
+    /** Severity level. Required for `error` and `log` types; optional for `analytics`. */
+    level?: LogLevel;
+    /** Arbitrary event name (e.g. `screen_view`, `button_click`). Used primarily for analytics. */
+    event?: string;
+    /** Human-readable event message. */
+    message: string;
+    /** Arbitrary key-value parameters attached to the event. */
+    params?: Record<string, unknown>;
+    /** Stack trace information (for error events). */
+    stackTrace?: {
+        frames?: unknown[];
+        raw?: string;
+    };
+    /** Logical module that produced the event (e.g. `messaging`, `websocket`). */
+    module?: string;
+    /** Unique device identifier. */
+    deviceId?: string;
+    /** Client platform (e.g. `ios`, `android`). */
+    platform?: string;
+    /** Application version. */
+    version?: string;
+    /** User identifier. */
+    userId?: string;
+    /** Session identifier. */
+    sessionId?: string;
+    /** ISO-8601 timestamp. Defaults to current time if omitted. */
+    timestamp?: string;
+}
+/** Response from `GET /api/config`. */
+interface ConfigResponse {
+    projectId: string;
+    disabled: string[];
+    sampleRates: Record<string, number>;
+    refreshIntervalSec: number;
+}
+/** Response from `POST /api/collect` (single event). */
+interface IngestResponse {
+    ok: boolean;
+    id?: string;
+    error?: string;
+    pattern?: string;
+}
+/** Response from `POST /api/collect/batch`. */
+interface BatchIngestResponse {
+    ok: boolean;
+    accepted: number;
+    rejected: number;
+    errors: Array<{
+        index: number;
+        reason: string;
+    }>;
+}
+/** A single metric key-value pair for batch operations. */
+interface MetricOp {
+    /** Metric key (e.g. `ws_connections`, `active_rooms`). */
+    key: string;
+    /** Numeric value to set. */
+    value: number;
+}
+/** SDK telemetry counters returned by {@link CollectorClient.getStats}. */
+interface CollectorStats {
+    /** Number of events successfully sent to the backend. */
+    sent: number;
+    /** Number of events dropped due to disabled filters. */
+    dropped: number;
+    /** Number of events that failed to send (network/API errors). */
+    failed: number;
+    /** Current number of events waiting in the batch queue. */
+    queueSize: number;
+}
+
+declare class CollectorClient {
+    private config;
+    private queue;
+    private disabledPatterns;
+    private configRefreshTimer;
+    private initialized;
+    private _lastConfig;
+    private _dropped;
+    private _userId;
+    private _sessionId;
+    private _module;
+    private _deviceId;
+    constructor(config: CollectorConfig);
+    /**
+     * Initialize the client: fetches filter configuration from the server
+     * and starts the periodic config refresh timer.
+     * Must be called before sending events.
+     */
+    init(): Promise<void>;
+    /**
+     * Flush all queued events to the server immediately.
+     * Returns when the send completes (or fails silently).
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop all timers and flush remaining events.
+     * Call before application exit or when the client is no longer needed.
+     */
+    destroy(): void;
+    /** Set the user ID attached to all subsequent events. */
+    setUser(userId: string): void;
+    /** Set the session ID attached to all subsequent events. */
+    setSession(sessionId: string): void;
+    /** Set the default module name attached to all subsequent events. */
+    setModule(module: string): void;
+    /** Set the device ID attached to all subsequent events. */
+    setDevice(deviceId: string): void;
+    /**
+     * Send an error event.
+     * @param message  Error description.
+     * @param params   Optional parameters. The special `stackTrace` key is extracted
+     *                 and sent as the structured `stackTrace.raw` field.
+     */
+    error(message: string, params?: Record<string, unknown> & {
+        stackTrace?: string;
+    }): void;
+    /**
+     * Send a log event with an explicit level.
+     * @param level   Severity: `fatal`, `error`, `warn`, `info`, or `debug`.
+     * @param message Log message.
+     * @param params  Optional key-value parameters.
+     */
+    log(level: LogLevel, message: string, params?: Record<string, unknown>): void;
+    /** Shorthand for `log('fatal', message, params)`. */
+    fatal(message: string, params?: Record<string, unknown>): void;
+    /** Shorthand for `log('warn', message, params)`. */
+    warn(message: string, params?: Record<string, unknown>): void;
+    /** Shorthand for `log('info', message, params)`. */
+    info(message: string, params?: Record<string, unknown>): void;
+    /** Shorthand for `log('debug', message, params)`. */
+    debug(message: string, params?: Record<string, unknown>): void;
+    /**
+     * Send an analytics event.
+     * @param event   Event name (e.g. `screen_view`, `button_click`).
+     * @param message Human-readable description (e.g. screen name or action label).
+     * @param params  Optional key-value parameters.
+     */
+    analytics(event: string, message: string, params?: Record<string, unknown>): void;
+    /**
+     * Set a single metric value. Sent immediately (not batched).
+     * @param key   Metric key (e.g. `ws_connections`).
+     * @param value Numeric value.
+     */
+    metric(key: string, value: number): Promise<void>;
+    /**
+     * Set multiple metric values in one request. Sent immediately (not batched).
+     * Backend accepts up to 100 operations per call.
+     * @param ops Array of `{ key, value }` pairs.
+     */
+    metricBatch(ops: MetricOp[]): Promise<void>;
+    /**
+     * Send a single event immediately via `POST /api/collect`, bypassing the batch queue.
+     * Useful for critical events that must not be delayed.
+     *
+     * The event is enriched with context (userId, sessionId, platform, etc.)
+     * and filtered against disabled patterns, same as queued events.
+     *
+     * @param event Partial event data. `type` and `message` are required.
+     */
+    send(event: Partial<CollectorEvent> & {
+        type: CollectorEvent['type'];
+        message: string;
+    }): Promise<void>;
+    /**
+     * Force-refresh the filter configuration from the server.
+     * Normally called automatically on the configured interval.
+     */
+    refreshConfig(): Promise<void>;
+    /**
+     * Returns the last successfully fetched server configuration,
+     * or `null` if no config has been loaded yet.
+     */
+    getConfig(): ConfigResponse | null;
+    /**
+     * Returns SDK telemetry counters: events sent, dropped (filtered), failed,
+     * and current queue size.
+     */
+    getStats(): CollectorStats;
+    /** Whether {@link init} has been called and completed successfully. */
+    get isInitialized(): boolean;
+    private buildEvent;
+    private enqueue;
+    private isDisabled;
+    private sendBatch;
+    private doFetch;
+    private handleError;
+    private log_debug;
+}
+
+export { type AnalyticsLevel, type BatchIngestResponse, CollectorClient, type CollectorConfig, type CollectorEvent, type CollectorStats, type ConfigResponse, type EventType, type IngestResponse, type LogLevel, type MetricOp };