TypeScript Types

The Seekora SDK is written in TypeScript and includes comprehensive type definitions.

Client Configuration

interface SeekoraClientConfig {
  storeId?: string;
  readSecret?: string;
  writeSecret?: string;
  baseUrl?: string;
  environment?: SeekoraEnvironment;
  timeout?: number;
  logLevel?: LogLevel;
  logger?: LoggerConfig;
  configFile?: string;
  userId?: string;
  anonId?: string;
  sessionId?: string;
  autoTrackSearch?: boolean;
  suggestionsDefaults?: {
    hitsPerPage?: number;
    include_dropdown_recommendations?: boolean;
    include_dropdown_product_list?: boolean;
    include_filtered_tabs?: boolean;
    time_range?: '7d' | '30d' | '90d';
  };
}

type SeekoraEnvironment = 'production' | 'staging';

type LogLevel = 'verbose' | 'info' | 'warn' | 'error' | 'silent';

interface LoggerConfig {
  level?: LogLevel;
  enableConsole?: boolean;
  enableFile?: boolean;
  format?: 'text' | 'json';
}

Search Types

Search Options

interface SearchOptions {
  q: string;
  per_page?: number;
  page?: number;
  filter?: string;
  filter_by?: string;
  facet_by?: string;
  sort?: string;
  sort_by?: string;
  analytics_tags?: string[];
  widget_mode?: boolean;
  search_fields?: string[];
  field_weights?: number[];
  return_fields?: string[];
  omit_fields?: string[];
  snippet_fields?: string[];
  full_snippet_fields?: string[];
  snippet_prefix?: string;
  snippet_suffix?: string;
  snippet_token_limit?: number;
  snippet_min_len?: number;
  include_snippets?: boolean;
  group_field?: string;
  group_size?: number;
  prefix_mode?: 'always' | 'fallback' | 'false';
  infix_mode?: 'always' | 'fallback' | 'false';
  typo_max?: number;
  typo_min_len_1?: number;
  typo_min_len_2?: number;
  typo_timeout_ms?: number;
  search_timeout_ms?: number;
  require_all_terms?: boolean;
  exact_match_boost?: boolean;
  cache_results?: boolean;
  apply_rules?: boolean;
  preset_name?: string;
  facet_search_text?: string;
  include_suggestions?: boolean;
  suggestions_limit?: number;
  max_facet_values?: number;
  stopword_sets?: string[];
  synonym_sets?: string[];
}

Search Response

interface SearchResponse {
  results: any[];
  totalResults: number;
  searchId?: string;
  context: SearchContext;
  facets?: Record<string, FacetData>;
  facet_counts?: Record<string, FacetData>;
  [key: string]: any;
}

// Multi-search types
interface MultiSearchQuery {
  q: string;
  per_page?: number;
  page?: number;
  filter_by?: string;
  facet_by?: string;
  sort_by?: string;
  return_fields?: string[];
  // ... all other SearchOptions fields
}

interface MultiSearchResponse {
  results: SearchResponse[];  // One per input query, same order
}

interface SearchContext {
  correlationId: string;
  searchId?: string;
  userId?: string;
  anonId: string;
  sessionId: string;
}

interface FacetData {
  counts: FacetCount[];
  stats?: FacetStats;
}

interface FacetCount {
  value: string;
  count: number;
  highlighted?: string;
}

interface FacetStats {
  min: number;
  max: number;
  avg: number;
  sum: number;
}

Query Suggestions Types

interface QuerySuggestionsOptions {
  hitsPerPage?: number;
  page?: number;
  analytics_tags?: string | string[];
  tags_match_mode?: 'any' | 'all';
  include_categories?: boolean;
  include_facets?: boolean;
  max_categories?: number;
  max_facets?: number;
  min_popularity?: number;
  time_range?: '7d' | '30d' | '90d';
  disable_typo_tolerance?: boolean;
  include_dropdown_recommendations?: boolean;
  include_dropdown_product_list?: boolean;
  include_filtered_tabs?: boolean;
  include_empty_query_recommendations?: boolean;
  filtered_tabs?: FilteredTab[];
  returnFullResponse?: boolean;
}

interface FilteredTab {
  id?: string;
  label: string;
  filter: string;
  count?: number;
}

interface QuerySuggestionsFullResponse {
  suggestions: SuggestionItem[];
  results?: any[];
  extensions?: QuerySuggestionsExtensions;
  raw?: any;
}

interface QuerySuggestionsExtensions {
  trending_searches?: TrendingSearch[];
  top_searches?: TopSearch[];
  related_searches?: RelatedSearch[];
  popular_brands?: PopularBrand[];
  filtered_tabs?: FilteredTab[];
}

interface SuggestionItem {
  query: string;
  popularity?: number;
  highlighted?: string;
}

interface TrendingSearch {
  query: string;
  count: number;
  trend: number;
}

interface TopSearch {
  query: string;
  count: number;
}

interface RelatedSearch {
  query: string;
  relevance: number;
}

interface PopularBrand {
  name: string;
  count: number;
  logo?: string;
}

Analytics Types

interface DataTypesEventPayload {
  event_name: string;
  query?: string;
  clicked_item_id?: string;
  position?: number;
  results_count?: number;
  value?: number;
  currency?: string;
  metadata?: Record<string, any>;
  timestamp?: string;
  user_id?: string;
  anon_id?: string;
  session_id?: string;
  analytics_tags?: string[];
}

interface ExtendedEventPayload extends DataTypesEventPayload {
  correlation_id?: string;
  search_id?: string;
}

interface TrackSearchParams {
  query: string;
  resultsCount: number;
  context?: SearchContext;
  analyticsTags?: string[];
  metadata?: Record<string, any>;
}

interface TrackImpressionParams {
  itemId: string;
  position: number;
  listType?: string;
  searchQuery?: string;
  context?: SearchContext;
  metadata?: Record<string, any>;
}

interface EventValidationResult {
  valid: boolean;
  message?: string;
  errors?: ValidationError[];
}

interface ValidationError {
  field: string;
  message: string;
  code: string;
}

Configuration Types

interface DataTypesIndexConfig {
  query_by?: string[];
  facet_by?: string[];
  sort_by?: string[];
  num_typos?: number;
  typo_tolerance?: 'none' | 'low' | 'medium' | 'high';
  prefix_search?: boolean;
  infix_search?: boolean;
  stemming?: boolean;
  remove_stop_words?: boolean;
  [key: string]: any;
}

interface QuerySuggestionsConfig {
  enabled: boolean;
  max_suggestions: number;
  minimum_letters: number;
  enable_personalization: boolean;
  [key: string]: any;
}

interface StoreInfo {
  storeId: string;
  storeName: string;
  onboardingStatus: string;
  createdAt: string;
  updatedAt: string;
  [key: string]: any;
}

User Types

interface UserIdentifiers {
  userId?: string;
  anonId: string;
  sessionId: string;
}

Logger Types

interface Logger {
  verbose(message: string, ...args: any[]): void;
  info(message: string, ...args: any[]): void;
  warn(message: string, ...args: any[]): void;
  error(message: string, ...args: any[]): void;
}

Importing Types

Import types from the SDK:

import {
  SeekoraClient,
  SeekoraClientConfig,
  SearchOptions,
  MultiSearchQuery,
  MultiSearchResponse,
  SearchResponse,
  SearchContext,
  QuerySuggestionsFullResponse,
  DataTypesEventPayload,
  DataTypesIndexConfig,
} from '@seekora-ai/search-sdk';

Type-safe Usage Examples

Search with Full Typing

import { SeekoraClient, SearchOptions, SearchResponse } from '@seekora-ai/search-sdk';

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
});

async function typedSearch(query: string): Promise<SearchResponse> {
  const options: Partial<SearchOptions> = {
    per_page: 20,
    filter_by: 'category:Electronics',
    facet_by: 'brand,price_range',
    sort_by: 'price:asc',
  };

  const results: SearchResponse = await client.search(query, options);
  
  // Type-safe access
  const total: number = results.totalResults;
  const items: any[] = results.results;
  const context = results.context;
  
  return results;
}

Suggestions with Full Typing

import { 
  SeekoraClient, 
  QuerySuggestionsFullResponse 
} from '@seekora-ai/search-sdk';

async function typedSuggestions(query: string): Promise<QuerySuggestionsFullResponse> {
  const response = await client.getSuggestions(query, {
    hitsPerPage: 10,
    include_dropdown_recommendations: true,
    returnFullResponse: true,
  }) as QuerySuggestionsFullResponse;

  // Type-safe access
  const suggestions = response.suggestions;
  const trending = response.extensions?.trending_searches ?? [];
  const related = response.extensions?.related_searches ?? [];

  return response;
}

Events with Full Typing

import { 
  SeekoraClient, 
  DataTypesEventPayload,
  SearchContext 
} from '@seekora-ai/search-sdk';

async function typedTracking(
  itemId: string,
  context: SearchContext
): Promise<void> {
  // Track click
  await client.trackClick(itemId, 1, context);

  // Track custom event with typed payload
  const payload: Partial<DataTypesEventPayload> = {
    event_name: 'add_to_cart',
    clicked_item_id: itemId,
    metadata: {
      quantity: 2,
      source: 'search_results',
    },
  };

  await client.trackEvent(payload, context);
}

Next Steps

• Overview - Search SDK introduction
• UI SDK - Pre-built UI components with full TypeScript support