@achado/client

Consumer-facing Achado JavaScript SDK package. This package provides a clean, simplified API for integrating Achado analytics into your web applications.

Overview

@achado/client is the recommended package for most users. It acts as the consumer-facing API layer (similar to 's js-client package) while importing functionality from the internal @achado/core package.

Installation

npm install @achado/client
# or
pnpm add @achado/client
# or
yarn add @achado/client

Quick Start

Basic Usage

import { AchadoClient, initialize } from '@achado/client';

// Option 1: Quick initialization (recommended)
const client = await initialize({
  apiKey: 'your-api-key-here',
  debug: true,
});

// Option 2: Manual initialization
const client = new AchadoClient({
  apiKey: 'your-api-key-here',
  debug: true,
});
await client.initialize();

// Track events
client.track('user_signed_up', {
  plan: 'pro',
  source: 'landing_page',
});

// Identify users
client.identify('user-123', {
  name: 'John Doe',
  email: '[email protected]',
  plan: 'pro',
});

With Plugins

import { AchadoClient } from '@achado/client';
import { WebAnalyticsPlugin } from '@achado/web-analytics';
import { SessionReplayPlugin } from '@achado/session-replay';

const webAnalytics = new WebAnalyticsPlugin({
  enablePageViews: true,
  enableClickTracking: true,
});

const sessionReplay = new SessionReplayPlugin({
  enabled: true,
  sampleRate: 0.1, // Record 10% of sessions
});

const client = new AchadoClient({
  apiKey: 'your-api-key-here',
  plugins: [webAnalytics, sessionReplay],
});

await client.initialize();

API Reference

Core Exports

// Main client class
export { AchadoClient } from '@achado/core';

// Type definitions
export type {
  AchadoConfig,
  AchadoEvent,
  AchadoUser,
  Logger,
  StorageAdapter,
  Plugin,
  PluginContext,
} from '@achado/core';

// Utility functions
export {
  generateId,
  generateSessionId,
  generateAnonymousId,
  getCurrentTimestamp,
} from '@achado/core';

// Global access and debugging
export { _getAchadoGlobal } from '@achado/core';

// Version information
export { SDK_VERSION, getClientMetadata } from '@achado/core';

// Plugin base class
export type { BasePlugin } from '@achado/core';

Convenience Functions

initialize(config: AchadoConfig): Promise<AchadoClient>

Quick initialization function that creates and initializes a client in one step:

const client = await initialize({
  apiKey: 'your-api-key',
  debug: true,
  userId: 'user-123',
});

instance(apiKey?: string): AchadoClient | undefined

Global instance accessor for debugging and multi-client scenarios:

// Get the default instance
const client = instance();

// Get a specific instance by API key
const specificClient = instance('your-api-key');

Global Access

For debugging purposes, you can access Achado instances globally:

// In browser console
window.__ACHADO__.instance(); // Get default instance
window.__ACHADO__.instance('your-api-key'); // Get specific instance
window.__ACHADO__.instances; // See all instances

TypeScript Support

This package includes full TypeScript definitions. All types are re-exported from the core package for convenience:

import type { AchadoConfig, AchadoEvent, AchadoUser } from '@achado/client';

const config: AchadoConfig = {
  apiKey: 'your-api-key',
  debug: true,
};

const user: AchadoUser = {
  userId: 'user-123',
  anonymousId: 'anon-456',
  sessionId: 'session-789',
  properties: {},
  traits: {},
};

Relationship to @achado/core

This package serves as the consumer-facing API layer:

• @achado/client: Public API for end users (this package)
• @achado/core: Internal infrastructure and implementation

This separation follows the same pattern as 's architecture:

• 's js-client ≈ Achado' client
• 's client-core ≈ Achado' core

Tree Shaking

This package is designed to be tree-shakable. Only the functions and classes you import will be included in your bundle:

// Only imports the client class and initialize function
import { AchadoClient, initialize } from '@achado/client';

// Only imports type definitions (zero runtime cost)
import type { AchadoConfig } from '@achado/client';

Examples

• Vanilla JavaScript Example
• Tree Shaking Examples

Advanced Usage

For advanced use cases, you can import directly from @achado/core:

// Direct core imports for advanced users
import { AchadoLogger, NetworkManager } from '@achado/core';

However, for most applications, the client package provides everything you need.

License

MIT