mytart 0.1.0

package/README.md

@@ -0,0 +1,234 @@
+# mytart
+
+**Multi-Yield Tracking & Analytics Relay Tool** — framework-agnostic analytics for any ESM JavaScript/TypeScript project.
+
+`mytart` makes direct HTTP calls to analytics provider endpoints via [axios](https://axios-http.com/) — no bloated SDK wrappers, no global state, no lock-in.
+
+## Features
+
+- 🔌 **7 providers out of the box**: Google Analytics 4, Mixpanel, Segment, Amplitude, Plausible, PostHog, Vercel Analytics
+- 🌐 **Universal**: works in Node.js, browsers, and any JS framework (Next.js, Remix, Astro, SvelteKit, etc.)
+- 🔷 **TypeScript-first**: precise typings, object-parameter style for great DX
+- 📦 **Dual ESM/CJS output**: works with `import` and `require`
+- 🪶 **Lightweight**: direct HTTP via axios, no SDK overhead
+- ✅ **Node.js ≥ 18**
+
+## Installation
+
+```bash
+npm install mytart
+# or
+pnpm add mytart
+# or
+yarn add mytart
+```
+
+## Quick Start
+
+```typescript
+import { Mytart } from 'mytart';
+
+const analytics = new Mytart({
+  providers: [
+    { provider: 'segment', writeKey: 'YOUR_WRITE_KEY' },
+    { provider: 'posthog', apiKey: 'phc_YOUR_KEY' },
+  ],
+  defaultUserId: 'user_123',
+});
+
+// Track an event
+await analytics.track({ event: 'signup', properties: { plan: 'pro' } });
+
+// Identify a user
+await analytics.identify({ userId: 'user_123', traits: { name: 'Alice', email: 'alice@example.com' } });
+
+// Track a page view
+await analytics.page({ url: 'https://example.com/pricing', name: 'Pricing' });
+```
+
+## Providers
+
+### Google Analytics 4
+
+```typescript
+{ provider: 'google-analytics', measurementId: 'G-XXXXXXXXXX', apiSecret: 'YOUR_SECRET', debug?: boolean }
+```
+
+### Mixpanel
+
+```typescript
+{ provider: 'mixpanel', token: 'YOUR_TOKEN', apiUrl?: string }
+```
+
+### Segment
+
+```typescript
+{ provider: 'segment', writeKey: 'YOUR_WRITE_KEY', apiUrl?: string }
+```
+
+### Amplitude
+
+```typescript
+{ provider: 'amplitude', apiKey: 'YOUR_API_KEY', apiUrl?: string }
+```
+
+### Plausible
+
+```typescript
+{ provider: 'plausible', domain: 'example.com', apiUrl?: string, userAgent?: string, xForwardedFor?: string }
+```
+
+> **Note**: Plausible does not support `identify()` — it returns an error result.
+
+### PostHog
+
+```typescript
+{ provider: 'posthog', apiKey: 'phc_YOUR_KEY', apiUrl?: string }
+```
+
+### Vercel Analytics
+
+```typescript
+{ provider: 'vercel-analytics', analyticsId: 'YOUR_ANALYTICS_ID', apiUrl?: string }
+```
+
+`analyticsId` is your `VERCEL_ANALYTICS_ID` environment variable (or the ID in your Vercel project's Analytics settings).  
+For on-Vercel deployments you can override `apiUrl` to `/_vercel/insights/event`.
+
+> **Note**: Vercel Analytics does not support `identify()` — it returns an error result (privacy-first by design).
+
+## API Reference
+
+### `new Mytart(config: MytartConfig)`
+
+```typescript
+interface MytartConfig {
+  providers: ProviderConfig[];
+  defaultUserId?: string;      // applied to every track/page call if no userId given
+  defaultAnonymousId?: string; // applied to every track/page call if no anonymousId given
+  debug?: boolean;
+}
+```
+
+Every provider config accepts an `enabled` field.  Providers are **off by default** — you must set `enabled: true` to activate a provider:
+
+```typescript
+const analytics = new Mytart({
+  providers: [
+    { provider: 'segment',  writeKey: 'YOUR_KEY', enabled: true  }, // active
+    { provider: 'mixpanel', token: 'YOUR_TOKEN'                  }, // skipped (off by default)
+  ],
+});
+```
+
+### `analytics.track(options: TrackOptions): Promise<TrackResult[]>`
+
+```typescript
+interface TrackOptions {
+  event: string;
+  properties?: Record<string, unknown>;
+  userId?: string;
+  anonymousId?: string;
+  timestamp?: Date;
+  context?: EventContext;
+}
+```
+
+### `analytics.identify(options: IdentifyOptions): Promise<TrackResult[]>`
+
+```typescript
+interface IdentifyOptions {
+  userId: string;
+  traits?: Record<string, unknown>;
+  anonymousId?: string;
+  timestamp?: Date;
+}
+```
+
+### `analytics.page(options: PageOptions): Promise<TrackResult[]>`
+
+```typescript
+interface PageOptions {
+  url: string;
+  name?: string;
+  referrer?: string;
+  properties?: Record<string, unknown>;
+  userId?: string;
+  anonymousId?: string;
+  timestamp?: Date;
+}
+```
+
+### `analytics.addProvider(config: ProviderConfig): void`
+
+Dynamically add a provider at runtime.
+
+### `analytics.removeProvider(name: string): void`
+
+Remove a provider by name.
+
+### `analytics.getProviders(): string[]`
+
+Returns the list of active provider names.
+
+### `TrackResult`
+
+Every method returns `Promise<TrackResult[]>` — one result per provider:
+
+```typescript
+interface TrackResult {
+  provider: string;
+  success: boolean;
+  statusCode?: number;
+  error?: MytartError;
+}
+
+interface MytartError {
+  message: string;
+  code: string;
+  provider: string;
+  originalError?: unknown;
+}
+```
+
+## TypeScript
+
+All types are exported:
+
+```typescript
+import type {
+  MytartConfig, BaseProviderConfig, ProviderConfig, TrackOptions, IdentifyOptions, PageOptions,
+  TrackResult, MytartError, EventContext, ProviderName,
+  GoogleAnalyticsConfig, MixpanelConfig, SegmentConfig,
+  AmplitudeConfig, PlausibleConfig, PostHogConfig, VercelAnalyticsConfig,
+} from 'mytart';
+```
+
+## Custom Providers
+
+Extend `BaseProvider` to create your own:
+
+```typescript
+import { BaseProvider, TrackOptions, IdentifyOptions, PageOptions, TrackResult } from 'mytart';
+
+export class MyProvider extends BaseProvider {
+  readonly name = 'my-provider';
+
+  async track(options: TrackOptions): Promise<TrackResult> {
+    // your HTTP call here
+    return this.buildSuccess(200);
+  }
+
+  async identify(options: IdentifyOptions): Promise<TrackResult> {
+    return this.buildSuccess(200);
+  }
+
+  async page(options: PageOptions): Promise<TrackResult> {
+    return this.buildSuccess(200);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,218 @@
+/**
+ * Fields shared by every provider configuration block.
+ * Set `enabled: true` to activate a provider for fan-out.
+ * Providers are **disabled by default** — omitting `enabled` (or setting it to
+ * `false`) means the provider is skipped entirely.
+ */
+interface BaseProviderConfig {
+    /** Whether this provider is active. Defaults to `false` when omitted. */
+    enabled?: boolean;
+}
+type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog' | 'vercel-analytics';
+interface GoogleAnalyticsConfig extends BaseProviderConfig {
+    provider: 'google-analytics';
+    measurementId: string;
+    apiSecret: string;
+    clientId?: string;
+    debug?: boolean;
+}
+interface MixpanelConfig extends BaseProviderConfig {
+    provider: 'mixpanel';
+    token: string;
+    apiUrl?: string;
+}
+interface SegmentConfig extends BaseProviderConfig {
+    provider: 'segment';
+    writeKey: string;
+    apiUrl?: string;
+}
+interface AmplitudeConfig extends BaseProviderConfig {
+    provider: 'amplitude';
+    apiKey: string;
+    apiUrl?: string;
+}
+interface PlausibleConfig extends BaseProviderConfig {
+    provider: 'plausible';
+    domain: string;
+    apiUrl?: string;
+    userAgent?: string;
+    xForwardedFor?: string;
+}
+interface PostHogConfig extends BaseProviderConfig {
+    provider: 'posthog';
+    apiKey: string;
+    apiUrl?: string;
+}
+interface VercelAnalyticsConfig extends BaseProviderConfig {
+    provider: 'vercel-analytics';
+    /**
+     * Your Vercel Analytics ID (the `VERCEL_ANALYTICS_ID` environment variable
+     * or the measurement ID shown in your Vercel project's Analytics settings).
+     */
+    analyticsId: string;
+    /**
+     * Override the default Vercel vitals ingestion endpoint.
+     * Defaults to `https://vitals.vercel-insights.com/v1/vitals`.
+     * On a Vercel deployment you may use `/_vercel/insights/event` instead.
+     */
+    apiUrl?: string;
+}
+type ProviderConfig = GoogleAnalyticsConfig | MixpanelConfig | SegmentConfig | AmplitudeConfig | PlausibleConfig | PostHogConfig | VercelAnalyticsConfig;
+interface MytartConfig {
+    providers: ProviderConfig[];
+    defaultUserId?: string;
+    defaultAnonymousId?: string;
+    debug?: boolean;
+}
+interface EventContext {
+    ip?: string;
+    userAgent?: string;
+    locale?: string;
+    page?: {
+        url?: string;
+        title?: string;
+        referrer?: string;
+    };
+    [key: string]: unknown;
+}
+interface TrackOptions {
+    event: string;
+    properties?: Record<string, unknown>;
+    userId?: string;
+    anonymousId?: string;
+    timestamp?: Date;
+    context?: EventContext;
+}
+interface IdentifyOptions {
+    userId: string;
+    traits?: Record<string, unknown>;
+    anonymousId?: string;
+    timestamp?: Date;
+}
+interface PageOptions {
+    name?: string;
+    url: string;
+    referrer?: string;
+    properties?: Record<string, unknown>;
+    userId?: string;
+    anonymousId?: string;
+    timestamp?: Date;
+}
+interface TrackResult {
+    provider: string;
+    success: boolean;
+    statusCode?: number;
+    error?: MytartError;
+}
+interface MytartError {
+    message: string;
+    code: string;
+    provider: string;
+    originalError?: unknown;
+}
+
+declare class Mytart {
+    private readonly providers;
+    private readonly config;
+    constructor(config: MytartConfig);
+    track(options: TrackOptions): Promise<TrackResult[]>;
+    identify(options: IdentifyOptions): Promise<TrackResult[]>;
+    page(options: PageOptions): Promise<TrackResult[]>;
+    addProvider(config: ProviderConfig): void;
+    removeProvider(name: string): void;
+    getProviders(): string[];
+}
+
+declare abstract class BaseProvider {
+    abstract readonly name: string;
+    abstract track(options: TrackOptions): Promise<TrackResult>;
+    abstract identify(options: IdentifyOptions): Promise<TrackResult>;
+    abstract page(options: PageOptions): Promise<TrackResult>;
+    protected buildError(message: string, code: string, originalError?: unknown): TrackResult;
+    protected buildSuccess(statusCode?: number): TrackResult;
+}
+
+declare class GoogleAnalyticsProvider extends BaseProvider {
+    readonly name = "google-analytics";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: GoogleAnalyticsConfig);
+    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, referrer, userId, anonymousId }: PageOptions): Promise<TrackResult>;
+}
+
+declare class MixpanelProvider extends BaseProvider {
+    readonly name = "mixpanel";
+    private readonly config;
+    private readonly http;
+    constructor(config: MixpanelConfig);
+    private encodeData;
+    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
+}
+
+declare class SegmentProvider extends BaseProvider {
+    readonly name = "segment";
+    private readonly config;
+    private readonly http;
+    private readonly baseUrl;
+    constructor(config: SegmentConfig);
+    private getAuth;
+    track({ event, properties, userId, anonymousId, timestamp, context }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits, anonymousId, timestamp }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, referrer, properties, userId, anonymousId, timestamp }: PageOptions): Promise<TrackResult>;
+}
+
+declare class AmplitudeProvider extends BaseProvider {
+    readonly name = "amplitude";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: AmplitudeConfig);
+    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
+}
+
+declare class PlausibleProvider extends BaseProvider {
+    readonly name = "plausible";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: PlausibleConfig);
+    private buildHeaders;
+    track({ event, properties, context }: TrackOptions): Promise<TrackResult>;
+    identify(_options: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, properties }: PageOptions): Promise<TrackResult>;
+}
+
+declare class PostHogProvider extends BaseProvider {
+    readonly name = "posthog";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: PostHogConfig);
+    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
+}
+
+declare class VercelAnalyticsProvider extends BaseProvider {
+    readonly name = "vercel-analytics";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: VercelAnalyticsConfig);
+    track({ event, properties, timestamp, context }: TrackOptions): Promise<TrackResult>;
+    /**
+     * Vercel Analytics is privacy-focused and does not support traditional user
+     * identification. This method returns an unsupported error.
+     */
+    identify(_options: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, referrer, properties, timestamp }: PageOptions): Promise<TrackResult>;
+}
+
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type EventContext, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult, type VercelAnalyticsConfig, VercelAnalyticsProvider };

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Fields shared by every provider configuration block.
+ * Set `enabled: true` to activate a provider for fan-out.
+ * Providers are **disabled by default** — omitting `enabled` (or setting it to
+ * `false`) means the provider is skipped entirely.
+ */
+interface BaseProviderConfig {
+    /** Whether this provider is active. Defaults to `false` when omitted. */
+    enabled?: boolean;
+}
+type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog' | 'vercel-analytics';
+interface GoogleAnalyticsConfig extends BaseProviderConfig {
+    provider: 'google-analytics';
+    measurementId: string;
+    apiSecret: string;
+    clientId?: string;
+    debug?: boolean;
+}
+interface MixpanelConfig extends BaseProviderConfig {
+    provider: 'mixpanel';
+    token: string;
+    apiUrl?: string;
+}
+interface SegmentConfig extends BaseProviderConfig {
+    provider: 'segment';
+    writeKey: string;
+    apiUrl?: string;
+}
+interface AmplitudeConfig extends BaseProviderConfig {
+    provider: 'amplitude';
+    apiKey: string;
+    apiUrl?: string;
+}
+interface PlausibleConfig extends BaseProviderConfig {
+    provider: 'plausible';
+    domain: string;
+    apiUrl?: string;
+    userAgent?: string;
+    xForwardedFor?: string;
+}
+interface PostHogConfig extends BaseProviderConfig {
+    provider: 'posthog';
+    apiKey: string;
+    apiUrl?: string;
+}
+interface VercelAnalyticsConfig extends BaseProviderConfig {
+    provider: 'vercel-analytics';
+    /**
+     * Your Vercel Analytics ID (the `VERCEL_ANALYTICS_ID` environment variable
+     * or the measurement ID shown in your Vercel project's Analytics settings).
+     */
+    analyticsId: string;
+    /**
+     * Override the default Vercel vitals ingestion endpoint.
+     * Defaults to `https://vitals.vercel-insights.com/v1/vitals`.
+     * On a Vercel deployment you may use `/_vercel/insights/event` instead.
+     */
+    apiUrl?: string;
+}
+type ProviderConfig = GoogleAnalyticsConfig | MixpanelConfig | SegmentConfig | AmplitudeConfig | PlausibleConfig | PostHogConfig | VercelAnalyticsConfig;
+interface MytartConfig {
+    providers: ProviderConfig[];
+    defaultUserId?: string;
+    defaultAnonymousId?: string;
+    debug?: boolean;
+}
+interface EventContext {
+    ip?: string;
+    userAgent?: string;
+    locale?: string;
+    page?: {
+        url?: string;
+        title?: string;
+        referrer?: string;
+    };
+    [key: string]: unknown;
+}
+interface TrackOptions {
+    event: string;
+    properties?: Record<string, unknown>;
+    userId?: string;
+    anonymousId?: string;
+    timestamp?: Date;
+    context?: EventContext;
+}
+interface IdentifyOptions {
+    userId: string;
+    traits?: Record<string, unknown>;
+    anonymousId?: string;
+    timestamp?: Date;
+}
+interface PageOptions {
+    name?: string;
+    url: string;
+    referrer?: string;
+    properties?: Record<string, unknown>;
+    userId?: string;
+    anonymousId?: string;
+    timestamp?: Date;
+}
+interface TrackResult {
+    provider: string;
+    success: boolean;
+    statusCode?: number;
+    error?: MytartError;
+}
+interface MytartError {
+    message: string;
+    code: string;
+    provider: string;
+    originalError?: unknown;
+}
+
+declare class Mytart {
+    private readonly providers;
+    private readonly config;
+    constructor(config: MytartConfig);
+    track(options: TrackOptions): Promise<TrackResult[]>;
+    identify(options: IdentifyOptions): Promise<TrackResult[]>;
+    page(options: PageOptions): Promise<TrackResult[]>;
+    addProvider(config: ProviderConfig): void;
+    removeProvider(name: string): void;
+    getProviders(): string[];
+}
+
+declare abstract class BaseProvider {
+    abstract readonly name: string;
+    abstract track(options: TrackOptions): Promise<TrackResult>;
+    abstract identify(options: IdentifyOptions): Promise<TrackResult>;
+    abstract page(options: PageOptions): Promise<TrackResult>;
+    protected buildError(message: string, code: string, originalError?: unknown): TrackResult;
+    protected buildSuccess(statusCode?: number): TrackResult;
+}
+
+declare class GoogleAnalyticsProvider extends BaseProvider {
+    readonly name = "google-analytics";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: GoogleAnalyticsConfig);
+    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, referrer, userId, anonymousId }: PageOptions): Promise<TrackResult>;
+}
+
+declare class MixpanelProvider extends BaseProvider {
+    readonly name = "mixpanel";
+    private readonly config;
+    private readonly http;
+    constructor(config: MixpanelConfig);
+    private encodeData;
+    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
+}
+
+declare class SegmentProvider extends BaseProvider {
+    readonly name = "segment";
+    private readonly config;
+    private readonly http;
+    private readonly baseUrl;
+    constructor(config: SegmentConfig);
+    private getAuth;
+    track({ event, properties, userId, anonymousId, timestamp, context }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits, anonymousId, timestamp }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, referrer, properties, userId, anonymousId, timestamp }: PageOptions): Promise<TrackResult>;
+}
+
+declare class AmplitudeProvider extends BaseProvider {
+    readonly name = "amplitude";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: AmplitudeConfig);
+    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
+}
+
+declare class PlausibleProvider extends BaseProvider {
+    readonly name = "plausible";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: PlausibleConfig);
+    private buildHeaders;
+    track({ event, properties, context }: TrackOptions): Promise<TrackResult>;
+    identify(_options: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, properties }: PageOptions): Promise<TrackResult>;
+}
+
+declare class PostHogProvider extends BaseProvider {
+    readonly name = "posthog";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: PostHogConfig);
+    track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
+    identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
+}
+
+declare class VercelAnalyticsProvider extends BaseProvider {
+    readonly name = "vercel-analytics";
+    private readonly config;
+    private readonly http;
+    private readonly endpoint;
+    constructor(config: VercelAnalyticsConfig);
+    track({ event, properties, timestamp, context }: TrackOptions): Promise<TrackResult>;
+    /**
+     * Vercel Analytics is privacy-focused and does not support traditional user
+     * identification. This method returns an unsupported error.
+     */
+    identify(_options: IdentifyOptions): Promise<TrackResult>;
+    page({ name, url, referrer, properties, timestamp }: PageOptions): Promise<TrackResult>;
+}
+
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type EventContext, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult, type VercelAnalyticsConfig, VercelAnalyticsProvider };