{"_id":"@achado/core","_rev":"2-f5e5f704451c29146d19858bd8a5433b","name":"@achado/core","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@achado/core","version":"0.0.1","_id":"@achado/core@0.0.1","maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"dist":{"shasum":"49242cdf98e77122416b9a715cf35f99b702dc48","tarball":"https://registry.npmjs.org/@achado/core/-/core-0.0.1.tgz","fileCount":62,"integrity":"sha512-tKheMvArrUWexaNGtBHh27Wp4G5602lsynO24AfGc96oOUwH11lqvW+zu6uceZvRRVo85CKp0JIHMXjgpgSZcA==","signatures":[{"sig":"MEYCIQDOStI8+Mx/mMwuIdrwHeWCR003vHr5nhE+ecltoS2GGQIhAIqYwsEtgxvIbGZRZty0bi9KGpsCf14Q2BuKhZVmXrhx","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":370373},"main":"dist/index.js","type":"commonjs","_from":"file:achado-core-0.0.1.tgz","types":"dist/types/index.d.ts","module":"dist/index.esm.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./utils":{"types":"./dist/types/utils.d.ts","import":"./dist/esm/utils.js","require":"./dist/cjs/utils.js"},"./client":{"types":"./dist/types/client.d.ts","import":"./dist/esm/client.js","require":"./dist/cjs/client.js"},"./logger":{"types":"./dist/types/logger.d.ts","import":"./dist/esm/logger.js","require":"./dist/cjs/logger.js"},"./plugin":{"types":"./dist/types/plugin.d.ts","import":"./dist/esm/plugin.js","require":"./dist/cjs/plugin.js"},"./network":{"types":"./dist/types/network.d.ts","import":"./dist/esm/network.js","require":"./dist/cjs/network.js"},"./storage":{"types":"./dist/types/storage.d.ts","import":"./dist/esm/storage.js","require":"./dist/cjs/storage.js"},"./package.json":"./package.json"},"scripts":{"dev":"rollup -c -w","lint":"eslint src --ext .ts,.tsx","test":"vitest run","build":"rollup -c","clean":"rm -rf dist","test:watch":"vitest","type-check":"tsc --noEmit"},"_npmUser":{"name":"achado","email":"achadolabs@gmail.com"},"_resolved":"/tmp/af36ed5dbfa2ce898f072ce5eac757ce/achado-core-0.0.1.tgz","_integrity":"sha512-tKheMvArrUWexaNGtBHh27Wp4G5602lsynO24AfGc96oOUwH11lqvW+zu6uceZvRRVo85CKp0JIHMXjgpgSZcA==","_npmVersion":"10.9.3","description":"Core SDK functionality for Achado analytics platform","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","dependencies":{"uuid":"^9.0.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/uuid":"^9.0.8"},"peerDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/core_0.0.1_1759924668612_0.2641974782488732","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@achado/core","version":"0.0.2","type":"commonjs","description":"Core SDK functionality for Achado analytics platform","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/types/index.d.ts","exports":{".":{"import":"./dist/esm/index.js","require":"./dist/cjs/index.js","types":"./dist/types/index.d.ts"},"./client":{"import":"./dist/esm/client.js","require":"./dist/cjs/client.js","types":"./dist/types/client.d.ts"},"./logger":{"import":"./dist/esm/logger.js","require":"./dist/cjs/logger.js","types":"./dist/types/logger.d.ts"},"./network":{"import":"./dist/esm/network.js","require":"./dist/cjs/network.js","types":"./dist/types/network.d.ts"},"./plugin":{"import":"./dist/esm/plugin.js","require":"./dist/cjs/plugin.js","types":"./dist/types/plugin.d.ts"},"./storage":{"import":"./dist/esm/storage.js","require":"./dist/cjs/storage.js","types":"./dist/types/storage.d.ts"},"./utils":{"import":"./dist/esm/utils.js","require":"./dist/cjs/utils.js","types":"./dist/types/utils.d.ts"},"./package.json":"./package.json"},"sideEffects":false,"dependencies":{"uuid":"^9.0.1"},"devDependencies":{"@types/uuid":"^9.0.8"},"peerDependencies":{},"publishConfig":{"access":"public"},"scripts":{"build":"rollup -c","dev":"rollup -c -w","test":"vitest run","test:watch":"vitest","lint":"eslint src --ext .ts,.tsx","type-check":"tsc --noEmit","clean":"rm -rf dist"},"_id":"@achado/core@0.0.2","_integrity":"sha512-2bDdr73oUUzzTR50WfkCNGZrHAThNKZLG0lO+Dr4eKgYQjsa5wkmfVZxgkcnad24YzxKXH8wgxozj2RHenMmAQ==","_resolved":"/tmp/08b674a1ca038e1d0f282aa10ddfa861/achado-core-0.0.2.tgz","_from":"file:achado-core-0.0.2.tgz","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-2bDdr73oUUzzTR50WfkCNGZrHAThNKZLG0lO+Dr4eKgYQjsa5wkmfVZxgkcnad24YzxKXH8wgxozj2RHenMmAQ==","shasum":"32be0333a02efda0363d218d60a6118154cfc340","tarball":"https://registry.npmjs.org/@achado/core/-/core-0.0.2.tgz","fileCount":62,"unpackedSize":370373,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAvEOCKSinLp+FYufqHMUFRxBdEHya3WIYvW9YCrBghxAiAN7c+Sa82T6ZP9vJljA2szHFY+EPTCeK8Vjl7pn9t0Wg=="}]},"_npmUser":{"name":"achado","email":"achadolabs@gmail.com"},"directories":{},"maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_0.0.2_1759937319024_0.2659464060894947"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-08T11:57:48.546Z","modified":"2025-10-08T15:28:39.382Z","0.0.1":"2025-10-08T11:57:48.803Z","0.0.2":"2025-10-08T15:28:39.209Z"},"description":"Core SDK functionality for Achado analytics platform","maintainers":[{"name":"achado","email":"achadolabs@gmail.com"}],"readme":"# @achado/core\n\n**⚠️ Internal Package**: This package contains the internal infrastructure for Achado analytics. Most users should use [`@achado/client`](../client) instead, which provides a cleaner consumer-facing API.\n\nThe core SDK for Achado analytics platform, providing foundational functionality for event tracking, user management, and data collection.\n\n## For End Users\n\n**Recommended**: Use [`@achado/client`](../client) package instead:\n\n```bash\nnpm install @achado/client\n```\n\nSee the [client package documentation](../client/README.md) for the recommended API.\n\n## For Advanced Users & Internal Use\n\nIf you need direct access to internal components:\n\n```bash\nnpm install @achado/core\n```\n\n### Direct Usage\n\n```typescript\nimport { AchadoClient } from '@achado/core';\n\nconst client = new AchadoClient({\n  apiKey: 'your-api-key',\n  debug: true,\n});\n\nawait client.initialize();\n\n// Track an event\nclient.track('button_clicked', {\n  buttonId: 'signup',\n  location: 'header',\n});\n\n// Identify a user\nclient.identify('user-123', {\n  name: 'John Doe',\n  email: 'john@example.com',\n});\n```\n\n## Package Architecture\n\nThis package serves as the internal infrastructure layer (similar to 's `client-core`):\n\n- **@achado/client**: Consumer-facing API (recommended for end users)\n- **@achado/core**: Internal infrastructure (this package)\n\nThe client package re-exports the necessary APIs from core while providing additional convenience functions.\n\n## Configuration\n\n### AchadoConfig\n\n```typescript\ninterface AchadoConfig {\n  apiKey: string; // Required: Your API key\n  apiEndpoint?: string; // API endpoint (default: production)\n  debug?: boolean; // Enable debug logging\n  userId?: string; // Initial user ID\n  sessionId?: string; // Custom session ID\n  enableTracking?: boolean; // Enable/disable tracking\n  enableSessionReplay?: boolean; // Enable session replay\n  enableFeatureTracking?: boolean; // Enable feature tracking\n  customProperties?: Record<string, any>; // Global properties\n}\n```\n\n## API Reference\n\n### AchadoClient\n\n#### Constructor\n\n```typescript\nnew AchadoClient(config: AchadoConfig)\n```\n\n#### Methods\n\n##### `initialize(): Promise<void>`\n\nInitialize the client and start tracking.\n\n##### `track(eventName: string, properties?: Record<string, any>): void`\n\nTrack a custom event.\n\n```typescript\nclient.track('purchase_completed', {\n  productId: 'prod-123',\n  price: 29.99,\n  currency: 'USD',\n});\n```\n\n##### `identify(userId: string, traits?: Record<string, any>): void`\n\nIdentify a user with optional traits.\n\n```typescript\nclient.identify('user-123', {\n  name: 'John Doe',\n  email: 'john@example.com',\n  plan: 'premium',\n});\n```\n\n##### `setUserProperties(properties: Record<string, any>): void`\n\nUpdate user properties.\n\n```typescript\nclient.setUserProperties({\n  lastLogin: new Date().toISOString(),\n  loginCount: 42,\n});\n```\n\n##### `getUser(): AchadoUser`\n\nGet current user information.\n\n##### `getConfig(): AchadoConfig`\n\nGet current configuration.\n\n##### `flush(): Promise<void>`\n\nManually flush the event queue.\n\n##### `reset(): void`\n\nReset the client state (clears user data).\n\n##### `destroy(): void`\n\nClean up and stop the client.\n\n### Event Queue\n\nThe core includes an intelligent event queue that:\n\n- **Batches Events**: Collects events for efficient transmission\n- **Auto-Flush**: Sends events based on size or time thresholds\n- **Retry Logic**: Handles network failures gracefully\n- **Background Processing**: Non-blocking event processing\n\n```typescript\n// Events are automatically queued and sent\nclient.track('event1', { data: 'value1' });\nclient.track('event2', { data: 'value2' });\n// Batch will be sent automatically\n```\n\n### Storage\n\n#### Browser Storage\n\n```typescript\nimport { BrowserStorageAdapter } from '@achado/core';\n\n// Use localStorage (default)\nconst storage = new BrowserStorageAdapter(false);\n\n// Use sessionStorage\nconst sessionStorage = new BrowserStorageAdapter(true);\n```\n\n#### Memory Storage\n\n```typescript\nimport { MemoryStorageAdapter } from '@achado/core';\n\nconst storage = new MemoryStorageAdapter();\n```\n\n#### Custom Storage\n\n```typescript\nimport { StorageAdapter } from '@achado/core';\n\nclass CustomStorage implements StorageAdapter {\n  getItem(key: string): string | null {\n    // Your implementation\n  }\n\n  setItem(key: string, value: string): void {\n    // Your implementation\n  }\n\n  removeItem(key: string): void {\n    // Your implementation\n  }\n}\n```\n\n### Utilities\n\n#### ID Generation\n\n```typescript\nimport {\n  generateId,\n  generateSessionId,\n  generateAnonymousId,\n} from '@achado/core';\n\nconst eventId = generateId(); // UUID v4\nconst sessionId = generateSessionId(); // session_timestamp_random\nconst anonId = generateAnonymousId(); // anon_uuid\n```\n\n#### Page Metadata\n\n```typescript\nimport { getPageMetadata } from '@achado/core';\n\nconst metadata = getPageMetadata();\n// Returns: { url, referrer, title, userAgent, viewport, screen }\n```\n\n#### Utility Functions\n\n```typescript\nimport { debounce, throttle, deepMerge } from '@achado/core';\n\n// Debounce function calls\nconst debouncedFunction = debounce(myFunction, 250);\n\n// Throttle function calls\nconst throttledFunction = throttle(myFunction, 1000);\n\n// Deep merge objects\nconst merged = deepMerge(target, source);\n```\n\n### Logger\n\n```typescript\nimport { AchadoLogger } from '@achado/core';\n\nconst logger = new AchadoLogger(true); // debug enabled\n\nlogger.debug('Debug message', { data: 'value' });\nlogger.info('Info message');\nlogger.warn('Warning message');\nlogger.error('Error message', error);\n```\n\n## Data Flow\n\n1. **Event Creation**: Events are created with metadata\n2. **Queue Addition**: Events are added to the internal queue\n3. **Batching**: Queue collects events until flush conditions are met\n4. **Transmission**: Batched events are sent to the API\n5. **Storage**: User state is persisted locally\n\n## Error Handling\n\nThe core SDK handles errors gracefully:\n\n- **Network Errors**: Events are retried with exponential backoff\n- **Storage Errors**: Fallback to memory storage\n- **API Errors**: Logged and events are preserved for retry\n\n## Performance\n\n- **Minimal Bundle Size**: Core functionality only\n- **Lazy Loading**: Optional features loaded on demand\n- **Efficient Queuing**: Batched network requests\n- **Memory Management**: Automatic cleanup of old events\n\n## Browser Support\n\n- Chrome 70+\n- Firefox 65+\n- Safari 12+\n- Edge 79+\n\n## TypeScript\n\nFull TypeScript support with comprehensive type definitions.\n\n```typescript\nimport type { AchadoEvent, AchadoUser, AchadoConfig } from '@achado/core';\n```\n","readmeFilename":"README.md"}