@varia-bly/variably-sdk
Version:
Official JavaScript/TypeScript SDK for Variably feature flags, experimentation, LLM experiments with React hooks, and real-time dynamic configurations
257 lines • 7.69 kB
TypeScript
/**
* Type definitions for Variably SDK
*/
export interface VariablyConfig {
/** API key for authentication */
apiKey: string;
/** Base URL for the GraphQL API (default: https://graphql.variably.tech) */
baseUrl?: string;
/** Environment (development, staging, production) */
environment?: string;
/** Request timeout in milliseconds (default: 5000) */
timeout?: number;
/** Number of retry attempts (default: 3) */
retryAttempts?: number;
/** Enable analytics tracking (default: true) */
enableAnalytics?: boolean;
/** Enable automatic event tracking (default: false) */
enableAutoTracking?: boolean;
/** Auto-tracking configuration */
autoTrackEvents?: AutoTrackConfig;
/** Cache configuration */
cache?: CacheConfig;
/** Real-time subscriptions configuration */
realTimeUpdates?: RealTimeUpdatesConfig;
}
export interface RealTimeUpdatesConfig {
/** Enable real-time Feature Gate updates via WebSocket (default: false) */
enabled?: boolean;
/** Project ID to subscribe to (required if enabled) */
projectId?: string;
/** Auto-invalidate cache when Feature Gates are updated (default: true) */
autoInvalidateCache?: boolean;
}
export interface CacheConfig {
/** Cache TTL in milliseconds (default: 300000 = 5 minutes) */
ttl?: number;
/** Maximum cache size (default: 1000) */
maxSize?: number;
/** Enable cache (default: true) */
enabled?: boolean;
}
export interface AutoTrackConfig {
/** Track page views automatically (default: true) */
pageViews?: boolean;
/** Track clicks automatically (default: true) */
clicks?: boolean;
/** Track scroll depth (default: true) */
scrollDepth?: boolean;
/** Track session duration (default: true) */
sessionDuration?: boolean;
/** Track form submissions (default: false) */
formSubmissions?: boolean;
/** Custom click selectors to track */
clickSelectors?: string[];
/** Exclude certain selectors from tracking */
excludeSelectors?: string[];
/** Minimum session duration to track (ms, default: 30000) */
minSessionDuration?: number;
/** Scroll depth thresholds to track (default: [25, 50, 75, 90]) */
scrollThresholds?: number[];
/** Conversion tracking configuration */
conversionTracking?: ConversionTrackingConfig;
}
export interface ConversionTrackingConfig {
/** Enable conversion tracking (default: false) */
enabled?: boolean;
/** Conversion event selectors and their event names */
conversionEvents?: ConversionEvent[];
/** Data extraction rules for conversion properties */
dataExtraction?: DataExtractionConfig;
}
export interface ConversionEvent {
/** CSS selector to match conversion elements */
selector: string;
/** Event name to track for this conversion */
eventName: string;
/** Additional properties to extract */
properties?: {
/** Property name in event */
[propertyName: string]: {
/** CSS selector to find the value */
selector: string;
/** Attribute to extract (textContent, href, data-*, etc.) */
attribute: string;
/** Transform function name (optional) */
transform?: 'number' | 'trim' | 'toLowerCase' | 'toUpperCase';
};
};
}
export interface DataExtractionConfig {
/** Extract position in list for elements */
trackPosition?: boolean;
/** Extract layout type from DOM */
trackLayoutType?: boolean;
/** Custom layout detection selectors */
layoutSelectors?: {
[layoutName: string]: string;
};
}
export interface UserContext {
/** Unique user identifier */
userId: string;
/** User email address */
email?: string;
/** User's country code */
country?: string;
/** User's preferred language */
language?: string;
/** Device/platform information */
platform?: string;
/** Application version */
version?: string;
/** User's IP address */
ipAddress?: string;
/** User agent string */
userAgent?: string;
/** Custom user attributes for targeting */
attributes?: Record<string, any>;
/** Session ID */
sessionId?: string;
}
export interface Event {
/** Event name */
name: string;
/** User ID associated with the event */
userId: string;
/** Event properties */
properties?: Record<string, any>;
/** Event timestamp (auto-generated if not provided) */
timestamp?: Date;
/** User context for the event */
context?: UserContext;
/** Session ID */
sessionId?: string;
}
export interface FlagResult {
/** Flag key */
key: string;
/** Flag value */
value: any;
/** Evaluation reason */
reason: string;
/** Rule ID that matched (if any) */
ruleId?: string;
/** Variation name (if any) */
variation?: string;
/** Whether the result came from cache */
cacheHit: boolean;
/** When the flag was evaluated */
evaluatedAt: Date;
/** Error if evaluation failed */
error?: Error;
}
export interface FlagEvaluationRequest {
flag_key: string;
context: UserContext;
}
export interface FlagEvaluationResponse {
flag_key: string;
value: any;
reason: string;
rule_id?: string;
experiment_id?: string;
variant_id?: string;
is_control?: boolean;
}
export interface GateEvaluationRequest {
gate_key: string;
context: UserContext;
}
export interface GateEvaluationResponse {
gate_key: string;
value: boolean;
reason: string;
rule_id?: string;
experiment_id?: string;
variant_id?: string;
is_control?: boolean;
environment: string;
success_metrics?: string[];
experimentId?: string;
variantId?: string;
isControl?: boolean;
successMetrics?: string[];
successMetricsSource?: string;
}
export interface EventTrackingRequest {
name: string;
user_id: string;
properties?: Record<string, any>;
timestamp: Date;
}
export interface ExperimentMetric {
userId: string;
metricKey: string;
value: number;
metadata?: Record<string, any>;
sessionId?: string;
timestamp?: Date;
}
export interface BatchFlagEvaluationRequest {
flag_keys: string[];
context: UserContext;
}
export interface BatchFlagEvaluationResponse {
results: Record<string, FlagEvaluationResponse>;
}
export interface CacheEntry<T = any> {
value: T;
timestamp: number;
ttl: number;
}
export interface SDKMetrics {
/** Total API calls made */
apiCalls: number;
/** Cache hits */
cacheHits: number;
/** Cache misses */
cacheMisses: number;
/** Total errors */
errors: number;
/** Average response time in ms */
averageLatency: number;
/** Cache hit rate (0-1) */
cacheHitRate: number;
/** Error rate (0-1) */
errorRate: number;
/** Flags evaluated */
flagsEvaluated: number;
/** Gates evaluated */
gatesEvaluated: number;
/** Events tracked */
eventsTracked: number;
/** SDK start time */
startTime: Date;
}
export interface DynamicConfigEvaluationRequest {
config_key: string;
context: UserContext;
}
export interface DynamicConfigEvaluationResponse {
config_key: string;
value: any;
reason: string;
rule_id?: string;
etag?: string;
version?: number;
updated_at?: string;
}
export interface DynamicConfigBatchRequest {
config_keys: string[];
context: UserContext;
}
export interface DynamicConfigBatchResponse {
results: Record<string, DynamicConfigEvaluationResponse>;
}
//# sourceMappingURL=types.d.ts.map