@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:

``bash
npm install @adopture/sdk-core


or

yarn add @adopture/sdk-core

or

pnpm add @adopture/sdk-core
`

API Reference

$3

#### 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

`typescript
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:

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

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

#### generateSessionId(): string

Generates session IDs for tracking user sessions:

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

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

#### generateAnonymousId(): string

Generates anonymous user IDs for tracking before user identification:

`typescript
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):

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

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

$3

#### isValidUUID(uuid: string): boolean

Validates UUID v4 format:

`typescript
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):

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

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

$3

#### isCryptoAvailable(): boolean

Checks if cryptographically secure random generation is available:

`typescript
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:

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

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

$3

The package exports comprehensive TypeScript interfaces and types:

`typescript
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

$3

Zod schemas for runtime validation:

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

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

$3

Utilities for managing SDK configuration across different environments and frameworks.

$3

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: team@adopture.com
- Website: adopture.com