OpenMobile SDK Core

Core TypeScript SDK for the OpenMobile platform. This is the foundation for all platform-specific SDKs.

Features

• 🚀 Expression System - 44 built-in functions for dynamic content
• 🔧 Configuration Management - Centralized config with runtime updates
• 🌐 HTTP Client - Full-featured HTTP client with interceptors
• 🎨 Theming System - Complete theme configuration
• 🚩 Feature Flags - Toggle features at runtime
• 🌍 Localization - Multi-language support
• 📦 Type-Safe - Full TypeScript support with strict types
• ⚡ Performance - Expression cache with LRU + TTL

Installation

npm install @openmobile/sdk-core

Quick Start

1. Initialize the SDK

import { OpenMobileSDK } from '@openmobile/sdk-core';

// Initialize with API key
const sdk = OpenMobileSDK.initialize('your-api-key', (config) => {
  // Configure SDK
  config.api.baseUrl = 'https://api.example.com';
  config.api.timeout = 30000;

  // Set variables
  config.variables.global = {
    appName: 'My App',
    version: '1.0.0',
  };

  config.variables.user = {
    name: 'John Doe',
    email: '[email protected]',
  };
});

2. Evaluate Expressions

// Simple variable access
const result = sdk.evaluateExpression('{{user.name}}');
// Output: "John Doe"

// String transformation
const upper = sdk.evaluateExpression('{{user.name | upper}}');
// Output: "JOHN DOE"

// Conditional logic
const status = sdk.evaluateExpression(
  '{{if(user.isActive, "Active", "Inactive")}}'
);

// Chained pipes
const formatted = sdk.evaluateExpression(
  '{{user.name | lower | capitalize}}'
);
// Output: "John doe"

3. Update Configuration at Runtime

// Update user context
sdk.setUserContext({
  name: 'Jane Smith',
  role: 'admin',
  isActive: true,
});

// Update global variables
sdk.setGlobalVariables({
  theme: 'dark',
  locale: 'es-ES',
});

// Toggle feature flags
sdk.setFeatureFlag('newFeature', true);

// Update theme
sdk.setTheme((theme) => {
  theme.colors.primary = '#007AFF';
  theme.fonts.body = 'Inter';
});

4. Subscribe to Configuration Changes

const unsubscribe = sdk.subscribe((newConfig) => {
  console.log('Configuration updated:', newConfig);
  // Update your UI
});

// Later: cleanup
unsubscribe();

Expression System

Syntax

// Variable access
{{variable}}
{{object.property}}
{{array[0]}}

// Pipes (transformations)
{{value | pipe}}
{{value | pipe1 | pipe2}}
{{value | pipe(arg1, arg2)}}

// Functions
{{functionName(arg1, arg2)}}
{{if(condition, trueValue, falseValue)}}

Variable Scopes (Priority Order)

1. Component - Highest priority, component-level state
2. Screen - Screen-specific variables
3. User - User context and authentication
4. Global - App-wide configuration
5. Constants - Built-in constants (lowest priority)

Available Functions

String Functions (10)

• upper, lower, capitalize - Case transformations
• trim, truncate - String manipulation
• replace, split, substring - String operations
• length, concat - String utilities

Number Functions (9)

• number, currency, percent - Formatting
• round, abs - Math operations
• multiply, divide, add, subtract - Arithmetic

Conditional Functions (11)

• if, ifEmpty - Conditionals
• equals, notEquals - Comparisons
• greaterThan, lessThan - Numeric comparisons
• and, or, not - Logical operations

Array Functions (9)

• length, first, last - Array access
• join, slice, includes - Array operations
• map, filter, sort - Array transformations

Object Functions (5)

• get, has - Object access
• keys, values - Object inspection
• merge - Object manipulation

→ See complete Expression Guide

Configuration Management

API Configuration

sdk.getConfigManager().setApiConfig({
  baseUrl: 'https://api.example.com',
  timeout: 30000,
  retries: 3,
  headers: {
    'X-Custom-Header': 'value',
  },
});

Authentication

sdk.getConfigManager().setAuthConfig({
  getToken: async () => {
    return await getAuthToken();
  },
  tokenHeader: 'Authorization',
  tokenPrefix: 'Bearer',
});

Theme Configuration

sdk.setTheme((theme) => {
  theme.colors = {
    primary: '#007AFF',
    secondary: '#5856D6',
    background: '#FFFFFF',
    text: '#000000',
  };

  theme.fonts = {
    heading: 'Inter Bold',
    body: 'Inter',
    mono: 'SF Mono',
  };

  theme.spacing = {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 32,
  };
});

Feature Flags

// Set feature flag
sdk.setFeatureFlag('darkMode', true);
sdk.setFeatureFlag('betaFeatures', false);

// Check feature flag
if (sdk.isFeatureEnabled('darkMode')) {
  // Enable dark mode
}

Localization

// Set locale
sdk.setLocale('es-ES');

// Get locale
const locale = sdk.getConfigManager().getLocale();

→ See complete Configuration Guide

HTTP Client

const httpClient = sdk.getHttpClient();

// GET request
const users = await httpClient.request(
  {
    method: 'GET',
    url: '/users',
    params: { page: 1, limit: 10 },
  },
  (data) => JSON.parse(data)
);

// POST request with auto auth
const newUser = await httpClient.request(
  {
    method: 'POST',
    url: '/users',
    data: { name: 'John Doe', email: '[email protected]' },
  },
  (data) => JSON.parse(data)
);

// Request with custom headers
const response = await httpClient.request(
  {
    method: 'GET',
    url: '/protected',
    headers: {
      'X-Custom-Header': 'value',
    },
  },
  (data) => JSON.parse(data)
);

Advanced Usage

Custom Expression Functions

import { FunctionRegistry } from '@openmobile/sdk-core';

// Add custom function
FunctionRegistry.register('myFunction', (value: string) => {
  return value.toUpperCase() + '!';
});

// Use in expressions
const result = sdk.evaluateExpression('{{name | myFunction}}');

Expression Cache Configuration

const sdk = OpenMobileSDK.initialize('api-key', (config) => {
  config.expressions = {
    cache: {
      enabled: true,
      ttl: 60000, // 1 minute
      maxSize: 100,
    },
  };
});

Resolve Expressions in Objects

const obj = {
  title: '{{user.name}}',
  subtitle: '{{user.email | lower}}',
  score: '{{user.points | add(100)}}',
};

const resolved = sdk.resolveExpressions(obj);
// {
//   title: "John Doe",
//   subtitle: "[email protected]",
//   score: 1100
// }

TypeScript Types

import type {
  OpenMobileConfig,
  VariableScope,
  ExpressionConfig,
  ApiConfig,
  ThemeConfig,
} from '@openmobile/sdk-core';

// Use types in your code
const config: OpenMobileConfig = {
  apiKey: 'key',
  api: {
    baseUrl: 'https://api.example.com',
    timeout: 30000,
  },
  variables: {
    global: {},
    user: {},
  },
};

Examples

See complete examples in the examples directory:

• Web React Example

API Reference

Core Classes

OpenMobileSDK

Main SDK class with singleton pattern.

Methods:

• initialize(apiKey, config?) - Initialize SDK
• getInstance() - Get SDK instance
• getVersion() - Get SDK version
• evaluateExpression(expr, scope?) - Evaluate expression
• resolveExpressions(obj, scope?) - Resolve all expressions in object
• subscribe(listener) - Subscribe to config changes

ConfigManager

Manages all SDK configuration.

Methods:

• getConfig() - Get complete config
• setGlobalVariables(vars) - Update global variables
• setUserContext(user) - Update user context
• setTheme(update) - Update theme
• setFeatureFlag(name, value) - Set feature flag
• setLocale(locale) - Set locale

Evaluator

Expression evaluation engine.

Methods:

• evaluateString(expr, scope) - Evaluate expression string
• evaluate(ast, scope) - Evaluate AST

HttpClient

HTTP client with authentication and interceptors.

Methods:

• request(config, parser) - Make HTTP request

Testing

# Run all tests
npm test

# Run E2E tests
npm run test:e2e

# Run with coverage
npm run test:coverage

Performance

• Expression Parsing: ~0.1ms per expression (cached)
• Expression Evaluation: ~0.01ms per expression (cached)
• Cache Hit Rate: >95% in typical usage
• Memory Usage: ~5MB for 1000 cached expressions

Browser Support

• Chrome/Edge: Latest 2 versions
• Firefox: Latest 2 versions
• Safari: Latest 2 versions

Node.js Support

• Node.js 18.0+
• TypeScript 5.0+

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE for details.

Related Packages

• @openmobile/sdk-web - React/Web integration
• @openmobile/sdk-android - Android/Kotlin SDK
• @openmobile/sdk-ios - iOS/Swift SDK

Support

• 📧 Email: [email protected]
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues
• 📖 Docs: Full Documentation

Made with ❤️ by the OpenMobile team