@metrone-io/server 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,357 @@
+/**
+ * Shared types for the Metrone server SDK.
+ *
+ * These types mirror the Worker's RawEventPayload exactly so payloads pass
+ * validation on the ingestion side without translation.
+ */
+type EventSource = 'web' | 'voice' | 'chat' | 'assistant' | 'sms' | 'listing';
+interface MetroneServerConfig {
+    /** API key (required). Format: metrone_live_* or metrone_test_* */
+    apiKey: string;
+    /** Ingestion endpoint. Default: https://api.metrone.io */
+    endpoint?: string;
+    /** Max events to buffer before auto-flush. 0 = send immediately. Default: 10 */
+    batchSize?: number;
+    /** Milliseconds between auto-flushes. Default: 5000 */
+    flushIntervalMs?: number;
+    /** Max retries per request. Default: 3 */
+    maxRetries?: number;
+    /** Base delay for exponential backoff in ms. Default: 1000 */
+    retryBaseMs?: number;
+    /** Timeout per HTTP request in ms. Default: 10000 */
+    timeoutMs?: number;
+    /** Maximum events to buffer while offline or during backpressure. Default: 1000 */
+    maxQueueSize?: number;
+    /** Enable debug logging to stderr. Default: false */
+    debug?: boolean;
+    /** Custom fetch implementation (for edge runtimes or testing). */
+    fetch?: typeof globalThis.fetch;
+}
+interface EventPayload {
+    event_type: string;
+    event_name?: string;
+    source?: EventSource;
+    channel?: string;
+    page_url?: string;
+    page_path?: string;
+    page_title?: string;
+    referrer?: string;
+    session_id?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    ai_provider?: string;
+    ai_call_id?: string;
+    ai_session_id?: string;
+    ai_intent?: string;
+    ai_duration_sec?: number;
+    /** Agent identification — who sent this event */
+    agent_id?: string;
+    agent_type?: string;
+    /** Idempotency key to prevent duplicate processing */
+    idempotency_key?: string;
+    properties?: Record<string, unknown>;
+    timestamp?: string;
+}
+interface AICallData {
+    call_id: string;
+    provider?: string;
+    duration?: number;
+    intent?: string;
+    transcript_snippet?: string;
+    outcome?: string;
+    session_id?: string;
+    properties?: Record<string, unknown>;
+}
+interface AIChatData {
+    session_id: string;
+    provider?: string;
+    message_count?: number;
+    intent?: string;
+    resolved?: boolean;
+    duration?: number;
+    properties?: Record<string, unknown>;
+}
+interface AIIntentData {
+    intent: string;
+    confidence?: number;
+    source?: 'voice' | 'chat' | 'assistant';
+    properties?: Record<string, unknown>;
+}
+interface AISessionData {
+    session_id: string;
+    provider?: string;
+    action: 'start' | 'end' | 'timeout';
+    duration?: number;
+    properties?: Record<string, unknown>;
+}
+interface ConversionData {
+    conversion_type: string;
+    value?: number;
+    currency?: string;
+    properties?: Record<string, unknown>;
+}
+interface StatsParams {
+    days?: number;
+    from?: string | Date;
+    to?: string | Date;
+}
+interface EventsParams {
+    days?: number;
+    from?: string | Date;
+    to?: string | Date;
+    limit?: number;
+    offset?: number;
+    event_type?: string;
+    source?: EventSource;
+}
+interface PagesParams {
+    days?: number;
+    from?: string | Date;
+    to?: string | Date;
+    limit?: number;
+}
+interface SourcesParams {
+    days?: number;
+    from?: string | Date;
+    to?: string | Date;
+}
+interface ApiResponse<T = unknown> {
+    ok: boolean;
+    status: number;
+    data?: T;
+    error?: ApiError;
+}
+interface ApiError {
+    code: string;
+    message: string;
+    details?: unknown;
+    retry_after_ms?: number;
+}
+interface FlushResult {
+    sent: number;
+    failed: number;
+    errors: Array<{
+        index: number;
+        error: string;
+    }>;
+}
+interface StatsResponse {
+    total_events: number;
+    pageviews: number;
+    conversions: number;
+    unique_visitors: number;
+    unique_sessions: number;
+    ai_interactions: number;
+    conversion_rate: number;
+    bounce_rate: number;
+    period: {
+        from: string;
+        to: string;
+    };
+}
+interface EventRow {
+    event_id: string;
+    timestamp: string;
+    event_type: string;
+    event_name: string | null;
+    source: string;
+    page_url: string | null;
+    page_path: string | null;
+    referrer_domain: string | null;
+    country_code: string | null;
+    country: string | null;
+    region: string | null;
+    city: string | null;
+    browser: string | null;
+    os: string | null;
+    device_type: string | null;
+    utm_source: string | null;
+    utm_medium: string | null;
+    utm_campaign: string | null;
+    session_id: string | null;
+    properties: Record<string, unknown> | null;
+}
+interface EventsResponse {
+    data: EventRow[];
+    meta: {
+        limit: number;
+        offset: number;
+        count: number;
+        period: {
+            from: string;
+            to: string;
+        };
+    };
+}
+interface PageRow {
+    page_path: string;
+    page_url: string | null;
+    pageviews: number;
+    unique_sessions: number;
+    conversions: number;
+}
+interface PagesResponse {
+    data: PageRow[];
+}
+interface ChannelRow {
+    source: string;
+    events: number;
+    conversions: number;
+    unique_sessions: number;
+    share: number;
+}
+interface ReferrerRow {
+    referrer_domain: string;
+    events: number;
+    unique_sessions: number;
+}
+interface SourcesResponse {
+    channels: ChannelRow[];
+    referrers: ReferrerRow[];
+}
+interface LiveResponse {
+    active_visitors: number;
+    today_events: number;
+    today_pageviews: number;
+    today_sessions: number;
+    today_conversions: number;
+}
+
+/**
+ * MetroneServer — the main server-side SDK client.
+ *
+ * Zero dependencies. Uses global fetch (Node 18+, Deno, Bun, edge runtimes).
+ * Runtime-agnostic: no DOM, no window, no navigator, no localStorage.
+ *
+ * Features:
+ *  - Event ingestion (single + batch) with automatic batching
+ *  - AI tracking (calls, chats, intents, sessions)
+ *  - Read API (stats, events, pages, sources, live)
+ *  - Retry with exponential backoff + jitter
+ *  - Idempotency key support
+ *  - Agent identity tracking
+ *  - Graceful shutdown with flush()
+ */
+
+declare class MetroneServer {
+    private readonly config;
+    private queue;
+    private flushTimer;
+    private flushing;
+    private destroyed;
+    constructor(config: MetroneServerConfig);
+    /**
+     * Track a custom event. Queued for batch sending unless batchSize is 0.
+     */
+    track(eventType: string, data?: Partial<EventPayload>): void;
+    /**
+     * Track a page view.
+     */
+    pageview(url: string, title?: string, data?: Partial<EventPayload>): void;
+    /**
+     * Track a conversion event.
+     */
+    conversion(data: ConversionData): void;
+    /**
+     * Track an AI voice call.
+     */
+    trackAICall(data: AICallData): void;
+    /**
+     * Track an AI chat interaction.
+     */
+    trackAIChat(data: AIChatData): void;
+    /**
+     * Track an AI intent detection.
+     */
+    trackAIIntent(data: AIIntentData): void;
+    /**
+     * Track an AI session lifecycle event (start, end, timeout).
+     */
+    trackAISession(data: AISessionData): void;
+    /**
+     * Get aggregated analytics stats for a time period.
+     */
+    getStats(params?: StatsParams): Promise<StatsResponse>;
+    /**
+     * Get individual analytics events with pagination and filters.
+     */
+    getEvents(params?: EventsParams): Promise<EventsResponse>;
+    /**
+     * Get page analytics broken down by path.
+     */
+    getPages(params?: PagesParams): Promise<PagesResponse>;
+    /**
+     * Get traffic source and referrer analytics.
+     */
+    getSources(params?: SourcesParams): Promise<SourcesResponse>;
+    /**
+     * Get real-time live stats (active visitors, today's totals).
+     */
+    getLive(): Promise<LiveResponse>;
+    /**
+     * Immediately flush all queued events. Returns the result.
+     * Safe to call multiple times concurrently — only one flush runs at a time.
+     */
+    flush(): Promise<FlushResult>;
+    /**
+     * Flush remaining events, stop the auto-flush timer, and mark the
+     * client as destroyed. Subsequent calls will throw.
+     */
+    shutdown(): Promise<FlushResult>;
+    /** Number of events currently in the send queue. */
+    get queueSize(): number;
+    /** Whether shutdown() has been called. */
+    get isDestroyed(): boolean;
+    private assertNotDestroyed;
+    private buildDateParams;
+}
+
+/**
+ * Structured error types for the Metrone server SDK.
+ *
+ * All errors carry a machine-readable `code` that agents can switch on,
+ * plus a human-readable `message` for logs.
+ */
+declare class MetroneError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly retryable: boolean;
+    constructor(code: string, message: string, status?: number, retryable?: boolean);
+}
+declare class MetroneConfigError extends MetroneError {
+    constructor(message: string);
+}
+declare class MetroneAuthError extends MetroneError {
+    constructor(message?: string);
+}
+declare class MetroneRateLimitError extends MetroneError {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+declare class MetroneQuotaError extends MetroneError {
+    constructor(message?: string);
+}
+declare class MetroneNetworkError extends MetroneError {
+    constructor(message?: string);
+}
+declare class MetroneTimeoutError extends MetroneError {
+    constructor(timeoutMs: number);
+}
+declare class MetroneValidationError extends MetroneError {
+    readonly fields: Array<{
+        field: string;
+        message: string;
+    }>;
+    constructor(fields: Array<{
+        field: string;
+        message: string;
+    }>);
+}
+declare class MetroneServerError extends MetroneError {
+    constructor(status: number, message?: string);
+}
+
+export { type AICallData, type AIChatData, type AIIntentData, type AISessionData, type ApiError, type ApiResponse, type ChannelRow, type ConversionData, type EventPayload, type EventRow, type EventSource, type EventsParams, type EventsResponse, type FlushResult, type LiveResponse, MetroneAuthError, MetroneConfigError, MetroneError, MetroneNetworkError, MetroneQuotaError, MetroneRateLimitError, MetroneServer, type MetroneServerConfig, MetroneServerError, MetroneTimeoutError, MetroneValidationError, type PageRow, type PagesParams, type PagesResponse, type ReferrerRow, type SourcesParams, type SourcesResponse, type StatsParams, type StatsResponse };

package/dist/index.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Shared types for the Metrone server SDK.
+ *
+ * These types mirror the Worker's RawEventPayload exactly so payloads pass
+ * validation on the ingestion side without translation.
+ */
+type EventSource = 'web' | 'voice' | 'chat' | 'assistant' | 'sms' | 'listing';
+interface MetroneServerConfig {
+    /** API key (required). Format: metrone_live_* or metrone_test_* */
+    apiKey: string;
+    /** Ingestion endpoint. Default: https://api.metrone.io */
+    endpoint?: string;
+    /** Max events to buffer before auto-flush. 0 = send immediately. Default: 10 */
+    batchSize?: number;
+    /** Milliseconds between auto-flushes. Default: 5000 */
+    flushIntervalMs?: number;
+    /** Max retries per request. Default: 3 */
+    maxRetries?: number;
+    /** Base delay for exponential backoff in ms. Default: 1000 */
+    retryBaseMs?: number;
+    /** Timeout per HTTP request in ms. Default: 10000 */
+    timeoutMs?: number;
+    /** Maximum events to buffer while offline or during backpressure. Default: 1000 */
+    maxQueueSize?: number;
+    /** Enable debug logging to stderr. Default: false */
+    debug?: boolean;
+    /** Custom fetch implementation (for edge runtimes or testing). */
+    fetch?: typeof globalThis.fetch;
+}
+interface EventPayload {
+    event_type: string;
+    event_name?: string;
+    source?: EventSource;
+    channel?: string;
+    page_url?: string;
+    page_path?: string;
+    page_title?: string;
+    referrer?: string;
+    session_id?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    ai_provider?: string;
+    ai_call_id?: string;
+    ai_session_id?: string;
+    ai_intent?: string;
+    ai_duration_sec?: number;
+    /** Agent identification — who sent this event */
+    agent_id?: string;
+    agent_type?: string;
+    /** Idempotency key to prevent duplicate processing */
+    idempotency_key?: string;
+    properties?: Record<string, unknown>;
+    timestamp?: string;
+}
+interface AICallData {
+    call_id: string;
+    provider?: string;
+    duration?: number;
+    intent?: string;
+    transcript_snippet?: string;
+    outcome?: string;
+    session_id?: string;
+    properties?: Record<string, unknown>;
+}
+interface AIChatData {
+    session_id: string;
+    provider?: string;
+    message_count?: number;
+    intent?: string;
+    resolved?: boolean;
+    duration?: number;
+    properties?: Record<string, unknown>;
+}
+interface AIIntentData {
+    intent: string;
+    confidence?: number;
+    source?: 'voice' | 'chat' | 'assistant';
+    properties?: Record<string, unknown>;
+}
+interface AISessionData {
+    session_id: string;
+    provider?: string;
+    action: 'start' | 'end' | 'timeout';
+    duration?: number;
+    properties?: Record<string, unknown>;
+}
+interface ConversionData {
+    conversion_type: string;
+    value?: number;
+    currency?: string;
+    properties?: Record<string, unknown>;
+}
+interface StatsParams {
+    days?: number;
+    from?: string | Date;
+    to?: string | Date;
+}
+interface EventsParams {
+    days?: number;
+    from?: string | Date;
+    to?: string | Date;
+    limit?: number;
+    offset?: number;
+    event_type?: string;
+    source?: EventSource;
+}
+interface PagesParams {
+    days?: number;
+    from?: string | Date;
+    to?: string | Date;
+    limit?: number;
+}
+interface SourcesParams {
+    days?: number;
+    from?: string | Date;
+    to?: string | Date;
+}
+interface ApiResponse<T = unknown> {
+    ok: boolean;
+    status: number;
+    data?: T;
+    error?: ApiError;
+}
+interface ApiError {
+    code: string;
+    message: string;
+    details?: unknown;
+    retry_after_ms?: number;
+}
+interface FlushResult {
+    sent: number;
+    failed: number;
+    errors: Array<{
+        index: number;
+        error: string;
+    }>;
+}
+interface StatsResponse {
+    total_events: number;
+    pageviews: number;
+    conversions: number;
+    unique_visitors: number;
+    unique_sessions: number;
+    ai_interactions: number;
+    conversion_rate: number;
+    bounce_rate: number;
+    period: {
+        from: string;
+        to: string;
+    };
+}
+interface EventRow {
+    event_id: string;
+    timestamp: string;
+    event_type: string;
+    event_name: string | null;
+    source: string;
+    page_url: string | null;
+    page_path: string | null;
+    referrer_domain: string | null;
+    country_code: string | null;
+    country: string | null;
+    region: string | null;
+    city: string | null;
+    browser: string | null;
+    os: string | null;
+    device_type: string | null;
+    utm_source: string | null;
+    utm_medium: string | null;
+    utm_campaign: string | null;
+    session_id: string | null;
+    properties: Record<string, unknown> | null;
+}
+interface EventsResponse {
+    data: EventRow[];
+    meta: {
+        limit: number;
+        offset: number;
+        count: number;
+        period: {
+            from: string;
+            to: string;
+        };
+    };
+}
+interface PageRow {
+    page_path: string;
+    page_url: string | null;
+    pageviews: number;
+    unique_sessions: number;
+    conversions: number;
+}
+interface PagesResponse {
+    data: PageRow[];
+}
+interface ChannelRow {
+    source: string;
+    events: number;
+    conversions: number;
+    unique_sessions: number;
+    share: number;
+}
+interface ReferrerRow {
+    referrer_domain: string;
+    events: number;
+    unique_sessions: number;
+}
+interface SourcesResponse {
+    channels: ChannelRow[];
+    referrers: ReferrerRow[];
+}
+interface LiveResponse {
+    active_visitors: number;
+    today_events: number;
+    today_pageviews: number;
+    today_sessions: number;
+    today_conversions: number;
+}
+
+/**
+ * MetroneServer — the main server-side SDK client.
+ *
+ * Zero dependencies. Uses global fetch (Node 18+, Deno, Bun, edge runtimes).
+ * Runtime-agnostic: no DOM, no window, no navigator, no localStorage.
+ *
+ * Features:
+ *  - Event ingestion (single + batch) with automatic batching
+ *  - AI tracking (calls, chats, intents, sessions)
+ *  - Read API (stats, events, pages, sources, live)
+ *  - Retry with exponential backoff + jitter
+ *  - Idempotency key support
+ *  - Agent identity tracking
+ *  - Graceful shutdown with flush()
+ */
+
+declare class MetroneServer {
+    private readonly config;
+    private queue;
+    private flushTimer;
+    private flushing;
+    private destroyed;
+    constructor(config: MetroneServerConfig);
+    /**
+     * Track a custom event. Queued for batch sending unless batchSize is 0.
+     */
+    track(eventType: string, data?: Partial<EventPayload>): void;
+    /**
+     * Track a page view.
+     */
+    pageview(url: string, title?: string, data?: Partial<EventPayload>): void;
+    /**
+     * Track a conversion event.
+     */
+    conversion(data: ConversionData): void;
+    /**
+     * Track an AI voice call.
+     */
+    trackAICall(data: AICallData): void;
+    /**
+     * Track an AI chat interaction.
+     */
+    trackAIChat(data: AIChatData): void;
+    /**
+     * Track an AI intent detection.
+     */
+    trackAIIntent(data: AIIntentData): void;
+    /**
+     * Track an AI session lifecycle event (start, end, timeout).
+     */
+    trackAISession(data: AISessionData): void;
+    /**
+     * Get aggregated analytics stats for a time period.
+     */
+    getStats(params?: StatsParams): Promise<StatsResponse>;
+    /**
+     * Get individual analytics events with pagination and filters.
+     */
+    getEvents(params?: EventsParams): Promise<EventsResponse>;
+    /**
+     * Get page analytics broken down by path.
+     */
+    getPages(params?: PagesParams): Promise<PagesResponse>;
+    /**
+     * Get traffic source and referrer analytics.
+     */
+    getSources(params?: SourcesParams): Promise<SourcesResponse>;
+    /**
+     * Get real-time live stats (active visitors, today's totals).
+     */
+    getLive(): Promise<LiveResponse>;
+    /**
+     * Immediately flush all queued events. Returns the result.
+     * Safe to call multiple times concurrently — only one flush runs at a time.
+     */
+    flush(): Promise<FlushResult>;
+    /**
+     * Flush remaining events, stop the auto-flush timer, and mark the
+     * client as destroyed. Subsequent calls will throw.
+     */
+    shutdown(): Promise<FlushResult>;
+    /** Number of events currently in the send queue. */
+    get queueSize(): number;
+    /** Whether shutdown() has been called. */
+    get isDestroyed(): boolean;
+    private assertNotDestroyed;
+    private buildDateParams;
+}
+
+/**
+ * Structured error types for the Metrone server SDK.
+ *
+ * All errors carry a machine-readable `code` that agents can switch on,
+ * plus a human-readable `message` for logs.
+ */
+declare class MetroneError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly retryable: boolean;
+    constructor(code: string, message: string, status?: number, retryable?: boolean);
+}
+declare class MetroneConfigError extends MetroneError {
+    constructor(message: string);
+}
+declare class MetroneAuthError extends MetroneError {
+    constructor(message?: string);
+}
+declare class MetroneRateLimitError extends MetroneError {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+declare class MetroneQuotaError extends MetroneError {
+    constructor(message?: string);
+}
+declare class MetroneNetworkError extends MetroneError {
+    constructor(message?: string);
+}
+declare class MetroneTimeoutError extends MetroneError {
+    constructor(timeoutMs: number);
+}
+declare class MetroneValidationError extends MetroneError {
+    readonly fields: Array<{
+        field: string;
+        message: string;
+    }>;
+    constructor(fields: Array<{
+        field: string;
+        message: string;
+    }>);
+}
+declare class MetroneServerError extends MetroneError {
+    constructor(status: number, message?: string);
+}
+
+export { type AICallData, type AIChatData, type AIIntentData, type AISessionData, type ApiError, type ApiResponse, type ChannelRow, type ConversionData, type EventPayload, type EventRow, type EventSource, type EventsParams, type EventsResponse, type FlushResult, type LiveResponse, MetroneAuthError, MetroneConfigError, MetroneError, MetroneNetworkError, MetroneQuotaError, MetroneRateLimitError, MetroneServer, type MetroneServerConfig, MetroneServerError, MetroneTimeoutError, MetroneValidationError, type PageRow, type PagesParams, type PagesResponse, type ReferrerRow, type SourcesParams, type SourcesResponse, type StatsParams, type StatsResponse };