@seekora-ai/search-sdk 0.2.3 → 0.2.5

package/dist/analytics-v3-api.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Analytics V3 Query API client
+ * Calls POST /api/v1/analytics/v3/* (and GET for journey) with JWT auth.
+ * Use from backend or admin apps that have a JWT; not for browser public SDK usage.
+ */
+import type { GenericResponse, SearchMetricsRequest, SearchMetrics, TopQueriesRequest, QueryMetric, ZeroResultQueriesRequest, ZeroResultQuery, ClickMetricsRequest, ClickMetrics, CTRByPositionRequest, PositionCTR, ConversionMetricsRequest, ConversionMetrics, RevenueAttributionRequest, RevenueAttribution, RecommendationMetricsRequest, RecommendationMetrics, RecommendationCTRRequest, RecommendationCTR, FunnelRequest, FunnelData, JourneyEvent } from './analytics-v3-types';
+export type { GenericResponse } from './analytics-v3-types';
+export interface AnalyticsV3ApiConfig {
+    /** Base URL of the API (e.g. https://api.seekora.ai) */
+    baseUrl: string;
+    /** Returns headers to attach (e.g. Authorization: Bearer <jwt>) */
+    getAuthHeaders: () => Promise<HeadersInit> | HeadersInit;
+    /** Optional fetch implementation (defaults to global fetch) */
+    fetch?: typeof fetch;
+}
+/**
+ * Client for Analytics V3 query endpoints.
+ * All POST endpoints expect JSON body with start_date, end_date (YYYY-MM-DD) and optional filters.
+ */
+export declare class AnalyticsV3Api {
+    private readonly config;
+    constructor(config: AnalyticsV3ApiConfig);
+    private post;
+    private get;
+    /** POST /api/v1/analytics/v3/search/metrics */
+    getSearchMetrics(req: SearchMetricsRequest): Promise<GenericResponse<SearchMetrics>>;
+    /** POST /api/v1/analytics/v3/search/top-queries */
+    getTopQueries(req: TopQueriesRequest): Promise<GenericResponse<QueryMetric[]>>;
+    /** POST /api/v1/analytics/v3/search/zero-results */
+    getZeroResultQueries(req: ZeroResultQueriesRequest): Promise<GenericResponse<ZeroResultQuery[]>>;
+    /** POST /api/v1/analytics/v3/clicks/metrics */
+    getClickMetrics(req: ClickMetricsRequest): Promise<GenericResponse<ClickMetrics>>;
+    /** POST /api/v1/analytics/v3/clicks/ctr */
+    getCTRByPosition(req: CTRByPositionRequest): Promise<GenericResponse<PositionCTR[]>>;
+    /** POST /api/v1/analytics/v3/conversions/metrics */
+    getConversionMetrics(req: ConversionMetricsRequest): Promise<GenericResponse<ConversionMetrics>>;
+    /** POST /api/v1/analytics/v3/conversions/revenue */
+    getRevenueAttribution(req: RevenueAttributionRequest): Promise<GenericResponse<RevenueAttribution>>;
+    /** POST /api/v1/analytics/v3/recommendations/metrics */
+    getRecommendationMetrics(req: RecommendationMetricsRequest): Promise<GenericResponse<RecommendationMetrics>>;
+    /** POST /api/v1/analytics/v3/recommendations/ctr */
+    getRecommendationCTR(req: RecommendationCTRRequest): Promise<GenericResponse<RecommendationCTR[]>>;
+    /** POST /api/v1/analytics/v3/funnel */
+    getFunnelAnalysis(req: FunnelRequest): Promise<GenericResponse<FunnelData>>;
+    /** GET /api/v1/analytics/v3/journey/:userKey */
+    getUserJourney(userKey: string, limit?: number): Promise<GenericResponse<JourneyEvent[]>>;
+}
+/**
+ * Create an Analytics V3 API client.
+ * Requires baseUrl and a way to provide JWT headers (e.g. from your auth provider).
+ */
+export declare function createAnalyticsV3Api(config: AnalyticsV3ApiConfig): AnalyticsV3Api;

package/dist/analytics-v3-api.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Analytics V3 Query API client
+ * Calls POST /api/v1/analytics/v3/* (and GET for journey) with JWT auth.
+ * Use from backend or admin apps that have a JWT; not for browser public SDK usage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsV3Api = void 0;
+exports.createAnalyticsV3Api = createAnalyticsV3Api;
+const DEFAULT_PAGE_SIZE = 100;
+const MAX_PAGE_SIZE = 1000;
+function resolveAuthHeaders(getAuthHeaders) {
+    const v = getAuthHeaders();
+    return Promise.resolve(v);
+}
+async function request(config, method, path, body) {
+    const url = `${config.baseUrl.replace(/\/$/, '')}${path}`;
+    const headers = {
+        'Content-Type': 'application/json',
+        ...(await resolveAuthHeaders(config.getAuthHeaders)),
+    };
+    const options = { method, headers };
+    if (body !== undefined && method === 'POST') {
+        options.body = JSON.stringify(body);
+    }
+    const fetchFn = config.fetch ?? (typeof fetch !== 'undefined' ? fetch : undefined);
+    if (!fetchFn) {
+        throw new Error('AnalyticsV3Api: fetch is not available. Provide config.fetch or use an environment with fetch.');
+    }
+    const res = await fetchFn(url, options);
+    const data = await res.json();
+    if (!res.ok) {
+        throw new Error(data?.message ?? `Analytics V3 API error: ${res.status}`);
+    }
+    return data;
+}
+/**
+ * Client for Analytics V3 query endpoints.
+ * All POST endpoints expect JSON body with start_date, end_date (YYYY-MM-DD) and optional filters.
+ */
+class AnalyticsV3Api {
+    constructor(config) {
+        this.config = config;
+    }
+    post(path, body) {
+        return request(this.config, 'POST', path, body);
+    }
+    get(path) {
+        return request(this.config, 'GET', path);
+    }
+    /** POST /api/v1/analytics/v3/search/metrics */
+    getSearchMetrics(req) {
+        return this.post('/api/v1/analytics/v3/search/metrics', req);
+    }
+    /** POST /api/v1/analytics/v3/search/top-queries */
+    getTopQueries(req) {
+        return this.post('/api/v1/analytics/v3/search/top-queries', req);
+    }
+    /** POST /api/v1/analytics/v3/search/zero-results */
+    getZeroResultQueries(req) {
+        return this.post('/api/v1/analytics/v3/search/zero-results', req);
+    }
+    /** POST /api/v1/analytics/v3/clicks/metrics */
+    getClickMetrics(req) {
+        return this.post('/api/v1/analytics/v3/clicks/metrics', req);
+    }
+    /** POST /api/v1/analytics/v3/clicks/ctr */
+    getCTRByPosition(req) {
+        return this.post('/api/v1/analytics/v3/clicks/ctr', req);
+    }
+    /** POST /api/v1/analytics/v3/conversions/metrics */
+    getConversionMetrics(req) {
+        return this.post('/api/v1/analytics/v3/conversions/metrics', req);
+    }
+    /** POST /api/v1/analytics/v3/conversions/revenue */
+    getRevenueAttribution(req) {
+        return this.post('/api/v1/analytics/v3/conversions/revenue', req);
+    }
+    /** POST /api/v1/analytics/v3/recommendations/metrics */
+    getRecommendationMetrics(req) {
+        return this.post('/api/v1/analytics/v3/recommendations/metrics', req);
+    }
+    /** POST /api/v1/analytics/v3/recommendations/ctr */
+    getRecommendationCTR(req) {
+        return this.post('/api/v1/analytics/v3/recommendations/ctr', req);
+    }
+    /** POST /api/v1/analytics/v3/funnel */
+    getFunnelAnalysis(req) {
+        return this.post('/api/v1/analytics/v3/funnel', req);
+    }
+    /** GET /api/v1/analytics/v3/journey/:userKey */
+    getUserJourney(userKey, limit) {
+        const q = limit != null ? `?limit=${Math.min(limit, MAX_PAGE_SIZE)}` : '';
+        return this.get(`/api/v1/analytics/v3/journey/${encodeURIComponent(userKey)}${q}`);
+    }
+}
+exports.AnalyticsV3Api = AnalyticsV3Api;
+/**
+ * Create an Analytics V3 API client.
+ * Requires baseUrl and a way to provide JWT headers (e.g. from your auth provider).
+ */
+function createAnalyticsV3Api(config) {
+    return new AnalyticsV3Api(config);
+}

package/dist/analytics-v3-types.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Analytics V3 API types
+ * Matches the Go backend v3 analytics structure: routes, requests, responses, and data types.
+ * Base path: POST /api/v1/analytics/v3/*
+ * Auth: JWT (Bearer).
+ */
+export interface GenericResponse<T> {
+    status: number;
+    message: string;
+    data?: T;
+}
+export interface AnalyticsV3BaseRequest {
+    start_date: string;
+    end_date: string;
+    xstoreid?: string;
+    page?: number;
+    page_size?: number;
+    granularity?: 'hour' | 'day' | 'week' | 'month';
+}
+export interface TimeSeriesPoint {
+    timestamp: string;
+    value: number;
+    count?: number;
+}
+export interface SearchMetricsRequest extends AnalyticsV3BaseRequest {
+    surface?: string;
+}
+export interface SearchMetrics {
+    total_searches: number;
+    unique_users: number;
+    unique_sessions: number;
+    total_results: number;
+    zero_result_searches: number;
+    zero_result_rate: number;
+    avg_results_per_search: number;
+    avg_latency_ms: number;
+    p95_latency_ms: number;
+    p99_latency_ms: number;
+    time_series?: TimeSeriesPoint[];
+}
+export interface TopQueriesRequest extends AnalyticsV3BaseRequest {
+    limit?: number;
+    sort_by?: string;
+    min_count?: number;
+    surface?: string;
+}
+export interface QueryMetric {
+    query: string;
+    normalized_query?: string;
+    search_count: number;
+    unique_users: number;
+    avg_results: number;
+    zero_result_count: number;
+    click_count?: number;
+    conversion_count?: number;
+    ctr?: number;
+    conversion_rate?: number;
+    avg_latency_ms: number;
+}
+export interface ZeroResultQueriesRequest extends AnalyticsV3BaseRequest {
+    limit?: number;
+    min_count?: number;
+}
+export interface ZeroResultQuery {
+    query: string;
+    count: number;
+    unique_users: number;
+    last_seen: string;
+}
+export interface ClickMetricsRequest extends AnalyticsV3BaseRequest {
+    click_subtype?: string;
+    surface?: string;
+}
+export interface ClickMetrics {
+    total_clicks: number;
+    unique_users: number;
+    unique_sessions: number;
+    unique_items: number;
+    attributed_clicks: number;
+    attribution_rate: number;
+    avg_position: number;
+    clicks_by_subtype?: Record<string, number>;
+    time_series?: TimeSeriesPoint[];
+}
+export interface CTRByPositionRequest extends AnalyticsV3BaseRequest {
+    max_position?: number;
+    surface?: string;
+}
+export interface PositionCTR {
+    position: number;
+    impressions: number;
+    clicks: number;
+    ctr: number;
+}
+export interface ConversionMetricsRequest extends AnalyticsV3BaseRequest {
+    conversion_type?: string;
+}
+export interface ConversionMetrics {
+    total_conversions: number;
+    unique_users: number;
+    total_revenue: number;
+    avg_order_value: number;
+    attributed_conversions: number;
+    attribution_rate: number;
+    unique_orders: number;
+    total_quantity: number;
+    conversions_by_type?: Record<string, number>;
+    time_series?: TimeSeriesPoint[];
+}
+export interface RevenueAttributionRequest extends AnalyticsV3BaseRequest {
+    attributed_only?: boolean;
+}
+export interface RevenueAttribution {
+    total_revenue: number;
+    attributed_revenue: number;
+    search_attributed_revenue: number;
+    reco_attributed_revenue: number;
+    attribution_rate: number;
+    avg_order_value: number;
+    time_series?: TimeSeriesPoint[];
+}
+export interface RecommendationMetricsRequest extends AnalyticsV3BaseRequest {
+    recommendation_type?: string;
+    surface?: string;
+}
+export interface RecommendationMetrics {
+    total_requests: number;
+    unique_users: number;
+    total_recommendations: number;
+    avg_recs_per_request: number;
+    fallback_rate: number;
+    avg_latency_ms: number;
+    p95_latency_ms: number;
+    requests_by_type?: Record<string, number>;
+    requests_by_surface?: Record<string, number>;
+    time_series?: TimeSeriesPoint[];
+}
+export interface RecommendationCTRRequest extends AnalyticsV3BaseRequest {
+    recommendation_type?: string;
+    surface?: string;
+    max_position?: number;
+}
+export interface RecommendationCTR {
+    recommendation_type: string;
+    surface?: string;
+    impressions: number;
+    clicks: number;
+    conversions: number;
+    ctr: number;
+    conversion_rate: number;
+}
+export interface FunnelRequest extends AnalyticsV3BaseRequest {
+    funnel_steps?: string[];
+}
+export interface FunnelStepResult {
+    name: string;
+    count: number;
+    unique_users: number;
+    dropoff_rate: number;
+    conversion_rate_from_previous: number;
+}
+export interface FunnelData {
+    steps: FunnelStepResult[];
+    overall_conversion_rate: number;
+}
+export interface JourneyEvent {
+    event_id: string;
+    event_type: string;
+    event_ts: string;
+    session_id: string;
+    search_id?: string;
+    query?: string;
+    item_id?: string;
+    position?: number;
+    value?: number;
+    is_attributed: boolean;
+    surface?: string;
+}
+export interface AnalyticsV3EventPayload {
+    event_id?: string;
+    event_ts?: string;
+    event_name?: string;
+    correlation_id?: string;
+    orgcode?: string;
+    xstoreid?: string;
+    user_id?: string;
+    anonymous_id?: string;
+    session_id?: string;
+    journey_id?: string;
+    request_id?: string;
+    search_id?: string;
+    suggestion_id?: string;
+    recommendation_id?: string;
+    query?: string;
+    results_count?: number;
+    latency_ms?: number;
+    normalized_query?: string;
+    clicked_item_id?: string;
+    click_type?: string;
+    clicked_value?: string;
+    original_query?: string;
+    position?: number;
+    section?: string;
+    tab_id?: string;
+    tab_label?: string;
+    tab_filter?: string;
+    suggestion_type?: string;
+    suggestion_source?: string;
+    suggestion_popularity?: number;
+    total_suggestions?: number;
+    is_attributed?: number;
+    suggestions_count?: number;
+    products_count?: number;
+    categories_count?: number;
+    brands_count?: number;
+    trending_count?: number;
+    recent_count?: number;
+    has_dropdown?: number;
+    has_filtered_tabs?: number;
+    impression_duration_ms?: number;
+    ip?: string;
+    device_type?: string;
+    is_mobile?: number;
+    is_tablet?: number;
+    is_touch_device?: number;
+    platform?: string;
+    device_fingerprint?: string;
+    screen_width?: number;
+    screen_height?: number;
+    viewport_width?: number;
+    viewport_height?: number;
+    color_depth?: number;
+    pixel_ratio?: number;
+    browser_name?: string;
+    browser_version?: string;
+    browser_language?: string;
+    timezone?: string;
+    timezone_offset?: number;
+    page_url?: string;
+    page_path?: string;
+    page_title?: string;
+    page_referrer?: string;
+    country?: string;
+    country_code?: string;
+    region?: string;
+    city?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    value?: number;
+    currency?: string;
+    analytics_tags?: string[];
+    custom_json?: string;
+    metadata?: Record<string, unknown>;
+}

package/dist/analytics-v3-types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Analytics V3 API types
+ * Matches the Go backend v3 analytics structure: routes, requests, responses, and data types.
+ * Base path: POST /api/v1/analytics/v3/*
+ * Auth: JWT (Bearer).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/client.d.ts

@@ -72,77 +72,23 @@ export interface SearchContext {
     anonId: string;
     /** Session ID */
     sessionId: string;
+    /** V3: organization code (optional, for analytics v3 backend) */
+    orgcode?: string;
+    /** V3: store identifier (optional, for analytics v3 backend) */
+    xstoreId?: string;
 }
 /**
- * Extended event payload with correlation_id, search_id, and browser context
- * (per identifier spec requirements)
- *
- * This extends the base DataTypesEventPayload to include:
- * - correlation_id: Required for linking events to search journeys
- * - search_id: Optional, but should be included when available
- * - Browser context: Screen, viewport, timezone, UTM, etc.
- *
- * Both correlation_id and search_id are set at the top level (not just in metadata) per spec.
+ * Extended event payload with correlation_id, search_id, browser context,
+ * and legacy anon_id for backward compatibility. DataTypesEventPayload (generated)
+ * already includes V3 fields: event_ts, anonymous_id, orgcode, xstoreid, is_mobile (0|1), etc.
  */
 export interface ExtendedEventPayload extends DataTypesEventPayload {
+    /** Legacy anonymous user ID (sent alongside anonymous_id for backward compat) */
+    anon_id?: string;
     /** Correlation ID for linking events to search journeys */
     correlation_id?: string;
     /** Search ID at top level (also in metadata for backward compat) */
     search_id?: string;
-    /** Screen width in pixels */
-    screen_width?: number;
-    /** Screen height in pixels */
-    screen_height?: number;
-    /** Viewport width in pixels */
-    viewport_width?: number;
-    /** Viewport height in pixels */
-    viewport_height?: number;
-    /** Color depth */
-    color_depth?: number;
-    /** Device pixel ratio */
-    pixel_ratio?: number;
-    /** Device fingerprint (if enabled) */
-    device_fingerprint?: string;
-    /** Browser name (chrome, firefox, safari, etc.) */
-    browser_name?: string;
-    /** Browser version */
-    browser_version?: string;
-    /** Browser language */
-    browser_language?: string;
-    /** User timezone (e.g., "America/New_York") */
-    timezone?: string;
-    /** Timezone offset in minutes */
-    timezone_offset?: number;
-    /** Current page URL */
-    page_url?: string;
-    /** Current page path */
-    page_path?: string;
-    /** Current page title */
-    page_title?: string;
-    /** Page referrer URL */
-    page_referrer?: string;
-    /** UTM source parameter */
-    utm_source?: string;
-    /** UTM medium parameter */
-    utm_medium?: string;
-    /** UTM campaign parameter */
-    utm_campaign?: string;
-    /** UTM term parameter */
-    utm_term?: string;
-    /** UTM content parameter */
-    utm_content?: string;
-    /** Connection type (wifi, cellular, etc.) */
-    connection_type?: string;
-    /** Effective connection type (4g, 3g, 2g, slow-2g) */
-    connection_effective_type?: string;
-    /** Platform (windows, macos, linux, android, ios) */
-    platform?: string;
-    /** Is mobile device */
-    is_mobile?: boolean;
-    /** Is tablet device */
-    is_tablet?: boolean;
-    /** Is touch-capable device */
-    is_touch_device?: boolean;
 }
 export interface SearchOptions {
     q: string;

package/dist/client.js

@@ -1039,21 +1039,27 @@ class SeekoraClient {
      * Ensures user_id or anon_id is present, and sets correlation_id/search_id at top level
      */
     buildEventPayload(event, context) {
+        const anonId = event.anonymous_id ?? event.anon_id ?? context?.anonId ?? this.anonId;
         const payload = {
             ...event,
             // Set identifiers from context or fall back to client defaults
             user_id: event.user_id || context?.userId || this.userId,
-            anon_id: event.anon_id || context?.anonId || this.anonId,
+            anon_id: anonId,
             session_id: event.session_id || context?.sessionId || this.sessionId,
             // Set correlation_id at top level if provided (per identifier spec)
             correlation_id: event.correlation_id || context?.correlationId,
             // Set search_id at top level (not just in metadata) if provided (per identifier spec)
             search_id: event.search_id || context?.searchId,
+            // V3 analytics: event timestamp (ISO) and anonymous_id alias for v3 backend compatibility
+            event_ts: event.event_ts ?? new Date().toISOString(),
+            anonymous_id: anonId,
+            orgcode: event.orgcode ?? context?.orgcode,
+            xstoreid: event.xstoreid ?? context?.xstoreId ?? this.storeId,
         };
         // Ensure either user_id or anon_id is present
         if (!payload.user_id && !payload.anon_id) {
-            // This should not happen as we always have anonId, but add check for safety
             payload.anon_id = this.anonId;
+            payload.anonymous_id = this.anonId;
         }
         // Also include search_id in metadata for backward compatibility
         if (payload.search_id && !payload.metadata) {
@@ -1103,10 +1109,10 @@ class SeekoraClient {
                 payload.connection_type = ctx.connection_type;
             if (ctx.connection_effective_type)
                 payload.connection_effective_type = ctx.connection_effective_type;
-            // Platform info
+            // Platform info (V3 API expects is_mobile/is_tablet as 0|1)
             payload.platform = ctx.platform;
-            payload.is_mobile = ctx.is_mobile;
-            payload.is_tablet = ctx.is_tablet;
+            payload.is_mobile = ctx.is_mobile ? 1 : 0;
+            payload.is_tablet = ctx.is_tablet ? 1 : 0;
             payload.is_touch_device = ctx.is_touch_device;
         }
         return payload;