Skip to main content

​
Full Configuration

import { Refine } from '@refine-ai/sdk';

const refine = new Refine({
  // Required
  apiKey: 'your-api-key',
  organizationId: 'org-uuid',
  catalogId: 'catalog-uuid',
  
  // Optional
  applicationType: 'web',
  debug: false,
  
  // Event tracking configuration
  events: {
    enabled: true,
    batchSize: 10,
    flushInterval: 5000,
    maxQueueSize: 1000,
    maxRetries: 3,
    persistence: 'localStorage',
    sessionTimeout: 30 * 60 * 1000
  },
  
  // Privacy configuration
  privacy: {
    respectDoNotTrack: false,
    anonymizeIp: false,
    requireConsent: false
  },
  
  // Global error handler
  onError: (error) => {
    console.error('Refine error:', error);
  }
});

​
Required Options

​
apiKey
string
required
Your Refine API key. Obtain from Dashboard → Settings → API Keys.
​
organizationId
string
required
Your organization UUID. Find at Dashboard → Settings → Organization.
​
catalogId
string
required
The catalog to search. Find at Dashboard → Catalogs.

​
Optional Options

​
applicationType
string
default:"web"
Application type identifier. Values: 'web', 'mobile', 'server'.
​
debug
boolean
default:"false"
Enable debug logging. Logs all requests, responses, and events to the console.
​
onError
(error: RefineError) => void
Global error handler called for all SDK errors. Useful for centralized error reporting.

​
Events Configuration

Control how events are batched, stored, and transmitted. 
events: {
  enabled: true,
  batchSize: 10,
  flushInterval: 5000,
  maxQueueSize: 1000,
  maxRetries: 3,
  persistence: 'localStorage',
  sessionTimeout: 30 * 60 * 1000
}
​
events.enabled
boolean
default:"true"
Enable or disable event tracking entirely.
​
events.batchSize
number
default:"10"
Number of events to batch before sending. Lower values = more frequent requests but fresher data.
​
events.flushInterval
number
default:"5000"
Maximum time (ms) between flushes, regardless of batch size.
​
events.maxQueueSize
number
default:"1000"
Maximum events to queue. Oldest events are dropped when exceeded.
​
events.maxRetries
number
default:"3"
Retry attempts for failed event submissions.
​
events.persistence
string
default:"localStorage"
Where to persist the event queue. Options:
  • 'localStorage' — Survives page refreshes (browser only)
  • 'sessionStorage' — Cleared on tab close
  • 'memory' — No persistence (lost on refresh)
  • 'none' — Disable persistence
​
events.sessionTimeout
number
default:"1800000"
Session timeout in milliseconds. Default is 30 minutes (30 * 60 * 1000).

​
Privacy Configuration

GDPR and privacy-related options. 
privacy: {
  respectDoNotTrack: false,
  anonymizeIp: false,
  requireConsent: false
}
​
privacy.respectDoNotTrack
boolean
default:"false"
When true, disables tracking if the browser’s Do Not Track setting is enabled.
​
privacy.anonymizeIp
boolean
default:"false"
When true, IP addresses are anonymized before storage.
​
privacy.requireConsent
boolean
default:"false"
When true, event tracking is paused until consent is granted via the ConsentPlugin.

​
Configuration Patterns

​
Development vs Production

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: process.env.REFINE_ORG_ID,
  catalogId: process.env.REFINE_CATALOG_ID,
  debug: process.env.NODE_ENV === 'development',
  events: {
    enabled: process.env.NODE_ENV === 'production',
    persistence: process.env.NODE_ENV === 'production' 
      ? 'localStorage' 
      : 'memory'
  }
});

​
GDPR Compliance

import { Refine, ConsentPlugin } from '@refine-ai/sdk';

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789',
  privacy: {
    respectDoNotTrack: true,
    anonymizeIp: true,
    requireConsent: true
  }
});

const consentPlugin = new ConsentPlugin({
  required: true,
  onConsentRequired: () => {
    showConsentBanner();
  }
});

refine.use(consentPlugin);

// When user grants consent
function handleConsentGranted() {
  consentPlugin.grant();
}

​
High-Volume Sites

For high-traffic applications, increase batch size and queue limits: 
const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789',
  events: {
    batchSize: 50,
    flushInterval: 10000,
    maxQueueSize: 5000,
    maxRetries: 5
  }
});

​
Server-Side Rendering

For SSR environments where localStorage isn’t available: 
const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789',
  applicationType: 'server',
  events: {
    persistence: 'memory'
  }
});

​
Updating Configuration

The SDK doesn’t support runtime configuration changes. Create a new instance if you need different settings: 
// Don't do this
refine.config.debug = true; // ❌ Won't work

// Do this instead
const debugRefine = new Refine({
  ...baseConfig,
  debug: true
});

​
Next Steps

Text Search

Start searching

Plugins

Extend SDK functionality