@adopture/sdk-core

Core utilities and shared functionality for the Adopture SDK ecosystem. This package provides TypeScript types, validation schemas, configuration management, security utilities, and ID generation functions used across all Adopture SDK packages.

Features

• 🔧 TypeScript First - Complete TypeScript support with strict typing
• 🛡️ Security Utilities - API key validation and security helpers
• 🆔 ID Generation - UUID and specialized ID generators with crypto fallbacks
• ⚙️ Configuration Management - Flexible configuration system
• ✅ Validation Schemas - Zod-based schemas for data validation
• 🌐 Cross-Platform - Works in browsers, Node.js, and edge environments

Installation

This package is typically installed automatically as a dependency of other Adopture SDK packages:

npm install @adopture/sdk-core
# or
yarn add @adopture/sdk-core
# or  
pnpm add @adopture/sdk-core

API Reference

UUID and ID Generation

generateUUID(): string

Generates a UUID v4 compatible string using the most secure method available:

• Uses crypto.randomUUID() when available (modern browsers/Node.js)
• Falls back to crypto.getRandomValues() for older environments
• Final fallback to Math.random() for maximum compatibility

import { generateUUID } from '@adopture/sdk-core';

const id = generateUUID();
// "f47ac10b-58cc-4372-a567-0e02b2c3d479"

generateEventId(): string

Generates event-specific IDs with timestamp prefix for chronological ordering:

import { generateEventId } from '@adopture/sdk-core';

const eventId = generateEventId();
// "evt_lx2k8f_abc123def456789"

generateSessionId(): string

Generates session IDs for tracking user sessions:

import { generateSessionId } from '@adopture/sdk-core';

const sessionId = generateSessionId();
// "sess_lx2k8fabc123def456"

generateAnonymousId(): string

Generates anonymous user IDs for tracking before user identification:

import { generateAnonymousId } from '@adopture/sdk-core';

const anonId = generateAnonymousId();
// "anon_lx2k8fabc123def456789xyz"

generateShortId(length?: number): string

Generates short random strings for internal use (default length: 8):

import { generateShortId } from '@adopture/sdk-core';

const shortId = generateShortId(12);
// "abc123def456"

Validation Functions

isValidUUID(uuid: string): boolean

Validates UUID v4 format:

import { isValidUUID } from '@adopture/sdk-core';

isValidUUID('f47ac10b-58cc-4372-a567-0e02b2c3d479'); // true
isValidUUID('invalid-uuid'); // false

isValidEventId(eventId: string): boolean

Validates event ID format (supports both UUID and custom format):

import { isValidEventId } from '@adopture/sdk-core';

isValidEventId('f47ac10b-58cc-4372-a567-0e02b2c3d479'); // true
isValidEventId('evt_lx2k8f_abc123def456789'); // true
isValidEventId('invalid'); // false

Crypto Utilities

isCryptoAvailable(): boolean

Checks if cryptographically secure random generation is available:

import { isCryptoAvailable } from '@adopture/sdk-core';

if (isCryptoAvailable()) {
  console.log('Secure random generation available');
}

getUUIDGenerationInfo(): object

Returns information about the UUID generation method for debugging:

import { getUUIDGenerationInfo } from '@adopture/sdk-core';

const info = getUUIDGenerationInfo();
// {
//   method: 'native' | 'crypto_fallback' | 'math_fallback',
//   secure: boolean,
//   available: boolean
// }

TypeScript Types

The package exports comprehensive TypeScript interfaces and types:

import type {
  FeatureTrackerConfig,
  UserProperties,
  AdoptionEventData,
  ExposureEventData,
  // ... and many more
} from '@adopture/sdk-core';

Key interfaces include:

• FeatureTrackerConfig - Main configuration interface
• UserProperties - User property definitions
• AdoptionEventData - Feature adoption event structure
• ExposureEventData - Feature exposure event structure
• VisibilityTrackingOptions - Visibility tracking configuration

Validation Schemas

Zod schemas for runtime validation:

import { 
  userPropertiesSchema,
  adoptionEventSchema,
  configSchema 
} from '@adopture/sdk-core';

// Validate user properties
const result = userPropertiesSchema.parse(userData);

Configuration Management

Utilities for managing SDK configuration across different environments and frameworks.

Security Utilities

Functions for API key validation, environment detection, and security-related operations.

Usage with Other Adopture SDKs

This package is designed to be used by other Adopture SDK packages:

• @adopture/next - Next.js SDK
• @adopture/react - React SDK
• @adopture/vanilla - Vanilla JavaScript SDK

Most users should install the appropriate framework-specific SDK rather than using this package directly.

Browser Compatibility

• Modern browsers: Uses crypto.randomUUID() for maximum security
• Older browsers: Falls back to crypto.getRandomValues()
• Legacy environments: Uses Math.random() as final fallback

Supports all browsers that support ES2020+ features.

Node.js Compatibility

Requires Node.js 14.0.0 or higher.

Contributing

This package is part of the Adopture monorepo. Please see the main repository for contribution guidelines.

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues: adopture/logmind/issues
• Email: [email protected]
• Website: adopture.com