Configuration

The Seekora SDK supports multiple configuration methods with a clear priority order.

Configuration Priority

Configuration is loaded in the following order (highest priority first):

1. Code configuration - Options passed to SeekoraClient
2. Environment variables - SEEKORA_* environment variables
3. Config file - .seekora.json or similar files

Code Configuration

Pass configuration directly when creating the client:

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

const client = new SeekoraClient({
  // Required
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  
  // Optional - Authentication
  writeSecret: 'your-write-secret',  // For config updates
  
  // Optional - Environment
  environment: 'production',  // 'local' | 'stage' | 'production'
  baseUrl: 'https://custom-api.com',  // Custom API URL
  
  // Optional - Behavior
  timeout: 30000,  // Request timeout in ms
  autoTrackSearch: false,  // Auto-track search events
  
  // Optional - User Identification
  userId: 'user-123',  // Authenticated user ID
  anonId: 'anon-456',  // Anonymous ID
  sessionId: 'session-789',  // Session ID

  // Optional - Suggestions defaults (applied to all getSuggestions calls)
  suggestionsDefaults: {
    hitsPerPage: 8,
    include_dropdown_recommendations: true,
    include_filtered_tabs: true,
    time_range: '7d',
  },

  // Optional - Logging
  logLevel: 'info',  // 'verbose' | 'info' | 'warn' | 'error' | 'silent'
  logger: {
    level: 'info',
    enableConsole: true,
    enableFile: false,
    format: 'text',  // 'text' | 'json'
  },
  
  // Optional - Config file
  configFile: './custom-config.json',
});

Configuration Options Reference

Option	Type	Default	Description
storeId	string	-	Your Seekora store ID
readSecret	string	-	Read API secret
writeSecret	string	-	Write API secret (for config updates)
environment	string	'production'	Environment: 'production', 'staging'
suggestionsDefaults	object	-	Default options for getSuggestions() calls
baseUrl	string	-	Custom API base URL
timeout	number	30000	Request timeout in milliseconds
logLevel	string	'info'	Log level
userId	string	-	Authenticated user ID
anonId	string	auto	Anonymous user ID
sessionId	string	auto	Session ID
autoTrackSearch	boolean	false	Auto-track search events
configFile	string	-	Custom config file path
logger	object	-	Logger configuration

Environment Variables

Set configuration using environment variables:

# Required
export SEEKORA_STORE_ID="your-store-id"
export SEEKORA_READ_SECRET="your-read-secret"

# Optional
export SEEKORA_WRITE_SECRET="your-write-secret"
export SEEKORA_ENV="production"
export SEEKORA_BASE_URL="https://custom-api.com"
export SEEKORA_TIMEOUT="30000"
export SEEKORA_LOG_LEVEL="info"

Config File

Create a config file in your project:

.seekora.json

{
  "storeId": "your-store-id",
  "readSecret": "your-read-secret",
  "writeSecret": "your-write-secret",
  "environment": "production",
  "timeout": 30000,
  "logLevel": "info",
  "logger": {
    "level": "info",
    "enableConsole": true,
    "enableFile": false,
    "format": "text"
  }
}

Config File Locations

The SDK looks for config files in the following order:

1. .seekora.json (project root)
2. .seekora.yaml (project root)
3. .seekora.yml (project root)
4. seekora.config.json (project root)
5. seekora.config.yaml (project root)
6. seekora.config.yml (project root)
7. ~/.seekora.json (home directory)
8. ~/.seekora.yaml (home directory)

note

Config file loading only works in Node.js environments. For browser usage, use code configuration or window.SEEKORA_CONFIG.

Environments

The SDK has built-in support for multiple environments.

Option 1: Environment parameter

// Production (default)
const prodClient = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  environment: 'production',
});

// Staging
const stageClient = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  environment: 'staging',
});

Option 2: Custom base URL

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  baseUrl: 'https://custom-api.example.com',
});

Available environments

Environment	Base URL	Description
production	https://api.seekora.ai/api	Production (default)
staging	https://stage-api.seekora.ai/api	Staging / testing

Default: production when no environment or baseUrl is provided.

Logging

Configure logging behavior:

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  logLevel: 'verbose',
  logger: {
    level: 'verbose',
    enableConsole: true,
    enableFile: true,  // Node.js only
    format: 'json',    // 'text' | 'json'
  },
});

Log Levels

Level	Value	Description
verbose	0	Detailed debugging information
info	1	General information (default)
warn	2	Warning messages
error	3	Error messages only
silent	4	No logging

Using the Logger

const logger = client.getLogger();

logger.verbose('Detailed debug info');
logger.info('General information');
logger.warn('Warning message');
logger.error('Error occurred');

Store Configuration

Manage your store's search configuration:

Get Store Configuration

const config = await client.getConfig();

console.log('Query fields:', config.query_by);
console.log('Facet fields:', config.facet_by);
console.log('Typo tolerance:', config.typo_tolerance);

Update Store Configuration

Requires writeSecret:

await client.updateConfig({
  num_typos: 2,
  typo_tolerance: 'medium',
  query_by: ['title', 'description', 'brand'],
  facet_by: ['category', 'brand', 'price_range'],
});

Get Configuration Schema

const schema = await client.getConfigSchema();
console.log('Available options:', schema);

Get Store Information

const storeInfo = await client.getStoreInfo();

console.log('Store ID:', storeInfo.storeId);
console.log('Store Name:', storeInfo.storeName);
console.log('Onboarding Status:', storeInfo.onboardingStatus);

Query Suggestions Configuration

Get Configuration

const config = await client.getSuggestionsConfig();

console.log('Enabled:', config.enabled);
console.log('Max suggestions:', config.max_suggestions);
console.log('Minimum letters:', config.minimum_letters);

Update Configuration

Requires writeSecret:

await client.updateQuerySuggestionsConfig({
  enabled: true,
  max_suggestions: 20,
  minimum_letters: 2,
  enable_personalization: false,
});

Browser Configuration

For browser usage without environment variables:

<script>
  // Set global config before loading SDK
  window.SEEKORA_CONFIG = {
    storeId: 'your-store-id',
    readSecret: 'your-read-secret',
    environment: 'production',
  };
</script>
<script src="https://cdn.seekora.ai/sdk/seekora-sdk.min.js"></script>
<script>
  // SDK will use window.SEEKORA_CONFIG
  const { SeekoraClient } = window.SeekoraSDK;
  const client = new SeekoraClient();
</script>

Next Steps

• User Management - Configure user identification
• TypeScript Types - Type definitions reference