@cherrydotfun/collector-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cherry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,497 @@
+# @cherrydotfun/collector-sdk
+
+TypeScript SDK for Cherry Collector — event tracking, logging, and metrics.
+
+Collect errors, logs, and analytics events from your application and stream them to the Collector backend. Zero dependencies, works on browser, React Native, and Node.js.
+
+## Installation
+
+```bash
+npm install @cherrydotfun/collector-sdk
+```
+
+```bash
+yarn add @cherrydotfun/collector-sdk
+```
+
+```bash
+bun add @cherrydotfun/collector-sdk
+```
+
+## Quick Start
+
+Initialize the client, send events, and flush before exit:
+
+```typescript
+import { CollectorClient } from '@cherrydotfun/collector-sdk';
+
+const collector = new CollectorClient({
+  baseUrl: 'https://collector.cherry.fun',
+  apiKey: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+  platform: 'ios',
+  version: '2.1.0',
+});
+
+// Initialize: fetch filter config and start refresh timer
+await collector.init();
+
+// Set context (attached to all subsequent events)
+collector.setUser('wallet_address_or_user_id');
+collector.setSession('session_uuid');
+collector.setModule('messaging');
+collector.setDevice('device_id');
+
+// Send events
+collector.error('WebSocket connection failed', { url: '/ws' });
+collector.info('User logged in', { userId: 'wallet123' });
+collector.debug('Cache hit', { key: 'messages_dm_123' });
+collector.analytics('screen_view', 'ChatScreen', { fromScreen: 'RoomList' });
+collector.analytics('button_click', 'Send message', { hasAttachment: true });
+
+// Set metrics
+await collector.metric('ws_connections', 42);
+await collector.metricBatch([
+  { key: 'ws_connections', value: 42 },
+  { key: 'active_rooms', value: 15 },
+]);
+
+// Flush remaining events and stop timers
+await collector.flush();
+collector.destroy();
+```
+
+## Configuration
+
+Pass a `CollectorConfig` object to the constructor:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | string | required | Base URL of the Collector backend (e.g. `https://collector.cherry.fun`). |
+| `apiKey` | string | required | Project API key from the admin panel. |
+| `platform` | string | undefined | Client platform (e.g. `ios`, `android`, `web`, `server`). Attached to all events. |
+| `version` | string | undefined | Application version string (e.g. `2.1.0`). Attached to all events. |
+| `batchSize` | number | 10 | Number of events per batch before auto-flush. |
+| `flushIntervalMs` | number | 5000 | Milliseconds between automatic batch flushes. |
+| `configRefreshSec` | number | 300 | Seconds between config refreshes from server. |
+| `debug` | boolean | false | Enable debug logging to `console.debug`. |
+| `onError` | function | undefined | Called when network or API errors occur. Receives `(error, context)`. |
+
+## API Reference
+
+### Lifecycle
+
+#### `init(): Promise<void>`
+
+Initialize the client. Fetches filter configuration from the server and starts the periodic config refresh timer. Must be called before sending events.
+
+```typescript
+await collector.init();
+```
+
+#### `flush(): Promise<void>`
+
+Flush all queued events to the server immediately. Returns when the send completes (or fails silently).
+
+```typescript
+await collector.flush();
+```
+
+#### `destroy(): void`
+
+Stop all timers and flush remaining events. Call before application exit or when the client is no longer needed.
+
+```typescript
+collector.destroy();
+```
+
+### Context
+
+These setters attach context to all subsequent events:
+
+#### `setUser(userId: string): void`
+
+Set the user ID.
+
+```typescript
+collector.setUser('wallet_address_or_user_id');
+```
+
+#### `setSession(sessionId: string): void`
+
+Set the session ID.
+
+```typescript
+collector.setSession('session_uuid');
+```
+
+#### `setModule(module: string): void`
+
+Set the default module name.
+
+```typescript
+collector.setModule('messaging');
+```
+
+#### `setDevice(deviceId: string): void`
+
+Set the device ID.
+
+```typescript
+collector.setDevice('device_uuid_or_id');
+```
+
+### Errors
+
+#### `error(message: string, params?: Record<string, unknown> & { stackTrace?: string }): void`
+
+Send an error event. The special `stackTrace` key is extracted and sent as the structured `stackTrace.raw` field.
+
+```typescript
+try {
+  await fetchData();
+} catch (e) {
+  collector.error('Failed to fetch data', {
+    url: '/api/data',
+    stackTrace: e instanceof Error ? e.stack : undefined,
+  });
+}
+```
+
+### Logging
+
+#### `log(level: LogLevel, message: string, params?: Record<string, unknown>): void`
+
+Send a log event with an explicit level (`fatal`, `error`, `warn`, `info`, or `debug`).
+
+```typescript
+collector.log('warn', 'Slow query detected', { duration: 2500 });
+```
+
+#### `fatal(message: string, params?: Record<string, unknown>): void`
+
+Shorthand for `log('fatal', message, params)`.
+
+```typescript
+collector.fatal('Critical system failure');
+```
+
+#### `error(message: string, params?: Record<string, unknown>): void`
+
+Shorthand for `log('error', message, params)`. Note: this is different from the `error()` method above, which has special stackTrace handling.
+
+#### `warn(message: string, params?: Record<string, unknown>): void`
+
+Shorthand for `log('warn', message, params)`.
+
+```typescript
+collector.warn('High memory usage', { mb: 512 });
+```
+
+#### `info(message: string, params?: Record<string, unknown>): void`
+
+Shorthand for `log('info', message, params)`.
+
+```typescript
+collector.info('Server started', { port: 3000 });
+```
+
+#### `debug(message: string, params?: Record<string, unknown>): void`
+
+Shorthand for `log('debug', message, params)`.
+
+```typescript
+collector.debug('Cache miss', { key: 'user_settings_123' });
+```
+
+### Analytics
+
+#### `analytics(event: string, message: string, params?: Record<string, unknown>): void`
+
+Send an analytics event. The `event` parameter is an event name (e.g. `screen_view`, `button_click`), and `message` is a human-readable description.
+
+```typescript
+collector.analytics('screen_view', 'ChatScreen', {
+  fromScreen: 'RoomList',
+  roomType: 'dm',
+});
+
+collector.analytics('button_click', 'Send message', {
+  hasAttachment: true,
+  messageLength: 42,
+});
+```
+
+### Metrics
+
+Metrics are sent immediately (not batched).
+
+#### `metric(key: string, value: number): Promise<void>`
+
+Set a single metric value.
+
+```typescript
+await collector.metric('ws_connections', 42);
+await collector.metric('active_rooms', 15);
+```
+
+#### `metricBatch(ops: MetricOp[]): Promise<void>`
+
+Set multiple metric values in one request. The backend accepts up to 100 operations per call.
+
+```typescript
+await collector.metricBatch([
+  { key: 'ws_connections', value: 42 },
+  { key: 'active_rooms', value: 15 },
+  { key: 'cpu_usage', value: 34.5 },
+]);
+```
+
+### Direct Send
+
+#### `send(event: Partial<CollectorEvent> & { type: CollectorEvent['type']; message: string }): 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.
+
+```typescript
+await collector.send({
+  type: 'error',
+  level: 'error',
+  message: 'Critical error',
+  params: { severity: 'high' },
+});
+```
+
+### Configuration
+
+#### `getConfig(): ConfigResponse | null`
+
+Returns the last successfully fetched server configuration, or `null` if no config has been loaded yet.
+
+```typescript
+const config = collector.getConfig();
+if (config) {
+  console.log('Disabled patterns:', config.disabled);
+}
+```
+
+#### `refreshConfig(): Promise<void>`
+
+Force-refresh the filter configuration from the server. Normally called automatically on the configured interval.
+
+```typescript
+await collector.refreshConfig();
+```
+
+### Observability
+
+#### `getStats(): CollectorStats`
+
+Returns SDK telemetry counters: events sent, dropped (filtered), failed, and current queue size.
+
+```typescript
+const stats = collector.getStats();
+console.log(`Sent: ${stats.sent}, Dropped: ${stats.dropped}, Failed: ${stats.failed}`);
+```
+
+#### `isInitialized: boolean`
+
+Read-only getter. Whether `init()` has been called and completed successfully.
+
+```typescript
+if (collector.isInitialized) {
+  console.log('Ready to send events');
+}
+```
+
+## Error Handling
+
+Pass an `onError` callback to handle network and API errors:
+
+```typescript
+const collector = new CollectorClient({
+  baseUrl: 'https://collector.cherry.fun',
+  apiKey: 'xxxxx',
+  onError: (error, context) => {
+    console.error(`Collector error in ${context}:`, error.message);
+    // Log to your error tracking service, retry, etc.
+  },
+});
+
+await collector.init();
+```
+
+The `context` parameter indicates where the error occurred:
+- `sendBatch` - batch event send
+- `send` - direct event send
+- `metric` - metric set
+- `metricBatch` - batch metric set
+- `refreshConfig` - config refresh from server
+
+## Event Filtering
+
+The SDK fetches a filter configuration from the server on init and periodically refreshes it. Events matching disabled patterns are dropped client-side and not sent.
+
+Patterns are hierarchical:
+- `log.debug` — disable debug-level log events
+- `log.*` — disable all log events
+- `log` — disable all log events (alternate syntax)
+- `*` — disable all events
+
+When you call `collector.debug(...)`, the SDK checks if `log.debug` is in the disabled set. If so, the event is dropped locally (not sent), and the dropped counter is incremented.
+
+```typescript
+const stats = collector.getStats();
+console.log(`Events dropped: ${stats.dropped}`);
+```
+
+## Platform Support
+
+The SDK requires `globalThis.fetch` to be available:
+
+- **Browser:** Native fetch, or polyfill
+- **React Native:** Built-in fetch (works with `http://` and `https://`)
+- **Node.js 18+:** Native fetch
+
+For Node.js < 18, provide a fetch polyfill (e.g. `node-fetch`):
+
+```typescript
+import fetch from 'node-fetch';
+globalThis.fetch = fetch;
+
+const collector = new CollectorClient({ /* ... */ });
+```
+
+## Types
+
+All types are exported from `@cherrydotfun/collector-sdk`:
+
+```typescript
+import {
+  CollectorClient,
+  CollectorConfig,
+  CollectorEvent,
+  CollectorStats,
+  ConfigResponse,
+  EventType,
+  LogLevel,
+  AnalyticsLevel,
+  MetricOp,
+  IngestResponse,
+  BatchIngestResponse,
+} from '@cherrydotfun/collector-sdk';
+```
+
+### Type Reference
+
+| Type | Description |
+|------|-------------|
+| `CollectorClient` | Main client class for sending events and metrics. |
+| `CollectorConfig` | Configuration options for the client. |
+| `CollectorEvent` | Event payload sent to the backend. |
+| `CollectorStats` | SDK telemetry counters (sent, dropped, failed, queueSize). |
+| `ConfigResponse` | Server response from `GET /api/config` with disabled patterns. |
+| `EventType` | Union of `'error' \| 'log' \| 'analytics'`. |
+| `LogLevel` | Union of `'fatal' \| 'error' \| 'warn' \| 'info' \| 'debug'`. |
+| `AnalyticsLevel` | Union of well-known analytics events or any custom string. |
+| `MetricOp` | Single metric key-value pair for batch operations. |
+| `IngestResponse` | Response from single event send. |
+| `BatchIngestResponse` | Response from batch event send. |
+
+## React Native Example
+
+```typescript
+import { useEffect } from 'react';
+import { AppState } from 'react-native';
+import { CollectorClient } from '@cherrydotfun/collector-sdk';
+
+const collector = new CollectorClient({
+  baseUrl: 'https://collector.cherry.fun',
+  apiKey: 'xxxxx',
+  platform: 'android', // or 'ios'
+  version: '2.1.0',
+  debug: false,
+  onError: (error, context) => {
+    console.error(`Collector error [${context}]:`, error);
+  },
+});
+
+export function App() {
+  useEffect(() => {
+    const init = async () => {
+      await collector.init();
+      collector.setUser(userWallet);
+      collector.setSession(sessionId);
+      collector.setModule('chat');
+    };
+
+    init();
+
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'background') {
+        collector.flush();
+      }
+    });
+
+    return () => {
+      subscription.remove();
+      collector.flush();
+      collector.destroy();
+    };
+  }, []);
+
+  return (
+    // Your app components
+  );
+}
+```
+
+## Node.js Server Example
+
+```typescript
+import { CollectorClient } from '@cherrydotfun/collector-sdk';
+
+const collector = new CollectorClient({
+  baseUrl: 'https://collector.cherry.fun',
+  apiKey: 'xxxxx',
+  platform: 'server',
+  version: '1.0.0',
+  debug: process.env.DEBUG === 'true',
+});
+
+await collector.init();
+
+// Log application startup
+collector.info('Server started', { port: 3000, env: process.env.NODE_ENV });
+
+// Track unhandled errors
+process.on('uncaughtException', (error) => {
+  collector.error('Uncaught exception', {
+    name: error.name,
+    message: error.message,
+    stackTrace: error.stack,
+  });
+  collector.flush().finally(() => process.exit(1));
+});
+
+// On graceful shutdown
+process.on('SIGTERM', async () => {
+  console.log('Shutting down...');
+  await collector.flush();
+  collector.destroy();
+  process.exit(0);
+});
+```
+
+## Build Distribution
+
+The SDK is published in multiple formats:
+
+- **CommonJS** — `dist/index.js` for Node.js
+- **ES Modules** — `dist/index.mjs` for bundlers
+- **TypeScript Declarations** — `dist/index.d.ts`
+
+## License
+
+MIT