SuperSettings SDK

A comprehensive Node.js/Browser SDK for the SuperSettings microservice. This library provides type-safe access to all SuperSettings API endpoints with full CRUD operations, cascade resolution, authentication, and error handling.

Features

• ✅ Universal Compatibility: Works in Node.js and browsers (CommonJS/ES6 modules)
• ✅ Type Safety: Full TypeScript support with comprehensive type definitions
• ✅ Complete API Coverage: All SuperSettings endpoints (Global, Client, User, Dynamic settings)
• ✅ Cascade Resolution: Automatic hierarchy resolution (User → Client → Global)
• ✅ Authentication: Bearer, Basic, and Custom auth support
• ✅ Error Handling: Comprehensive error classes with retry logic
• ✅ Modern: Built with modern JavaScript features and best practices

Installation

npm install supersettings-sdk

For Node.js environments, you'll also need:

npm install cross-fetch

Quick Start

CommonJS (Node.js)

const { SuperSettingsClient } = require('supersettings-sdk');

const client = new SuperSettingsClient({
  baseURL: 'https://your-supersettings-api.com',
  auth: {
    type: 'bearer',
    token: 'your-api-token'
  }
});

ES Modules (Modern Node.js/Browser)

import { SuperSettingsClient } from 'supersettings-sdk';

const client = new SuperSettingsClient({
  baseURL: 'https://your-supersettings-api.com',
  auth: {
    type: 'bearer',
    token: 'your-api-token'
  }
});

Configuration

Authentication Types

Bearer Token

const client = new SuperSettingsClient({
  baseURL: 'https://api.supersettings.com',
  auth: {
    type: 'bearer',
    token: 'your-jwt-token'
  }
});

Basic Authentication

const client = new SuperSettingsClient({
  baseURL: 'https://api.supersettings.com',
  auth: {
    type: 'basic',
    username: 'your-username',
    password: 'your-password'
  }
});

Custom Headers

const client = new SuperSettingsClient({
  baseURL: 'https://api.supersettings.com',
  auth: {
    type: 'custom',
    headers: {
      'X-API-Key': 'your-api-key',
      'X-Organization-ID': 'your-org-id'
    }
  }
});

Advanced Configuration

const client = new SuperSettingsClient({
  baseURL: 'https://api.supersettings.com',
  auth: { /* auth config */ },
  timeout: 15000,        // Request timeout in ms (default: 10000)
  retryAttempts: 5,      // Number of retry attempts (default: 3)
  retryDelay: 2000       // Delay between retries in ms (default: 1000)
});

Usage Examples

Cascade Resolution (Recommended)

Get settings with automatic hierarchy resolution (User → Client → Global):

// Get setting with cascade resolution
const result = await client.getSetting('theme', {
  userId: 'user123',
  clientId: 'client456'
});

console.log(result.source); // 'user', 'client', or 'global'
console.log(result.value);  // The actual setting value
console.log(result.setting); // Full setting object

Global Settings

// Create or update global setting
await client.createOrUpdateGlobalSetting({
  settingKey: 'app.theme',
  settingValue: 'dark',
  description: 'Application theme preference'
});

// List all global settings
const globalSettings = await client.listGlobalSettings();

// Get specific global setting
const setting = await client.getGlobalSetting('setting-id');

// Update global setting
await client.updateGlobalSetting('setting-id', {
  settingValue: 'light',
  description: 'Updated theme preference'
});

// Delete global setting
await client.deleteGlobalSetting('setting-id');

Client Settings

// Get all settings for a client
const clientSettings = await client.getAllClientSettings('client123');

// Get specific client setting
const setting = await client.getClientSetting('client123', 'api.timeout');

// Create client setting
await client.createClientSetting({
  clientId: 'client123',
  settingKey: 'api.timeout',
  settingValue: 5000,
  description: 'API timeout for this client'
});

// Update client setting
await client.updateClientSetting('setting-id', {
  settingValue: 10000
});

User Settings

// Get all settings for a user
const userSettings = await client.getAllUserSettings('user123');

// Get specific user setting
const setting = await client.getUserSetting('user123', 'notifications.email');

// Create user setting
await client.createUserSetting({
  userId: 'user123',
  settingKey: 'notifications.email',
  settingValue: true,
  description: 'Email notification preference'
});

// Update user setting
await client.updateUserSetting('setting-id', {
  settingValue: false
});

Dynamic Settings

// Get all settings for a unique identifier
const dynamicSettings = await client.getAllDynamicSettings('feature123');

// Create dynamic setting
await client.createDynamicSetting({
  uniqueId: 'feature123',
  settingKey: 'feature.enabled',
  settingValue: true,
  description: 'Feature flag for new functionality'
});

Error Handling

The SDK provides comprehensive error handling with specific error types:

import { 
  SuperSettingsAPIError, 
  SuperSettingsNetworkError,
  SuperSettingsConfigError 
} from 'supersettings-sdk';

try {
  const setting = await client.getSetting('nonexistent');
} catch (error) {
  if (error instanceof SuperSettingsAPIError) {
    if (error.isNotFound()) {
      console.log('Setting not found');
    } else if (error.isForbidden()) {
      console.log('Insufficient permissions');
    }
    
    console.log('Status:', error.status);
    console.log('Response:', error.response);
  } else if (error instanceof SuperSettingsNetworkError) {
    console.log('Network error:', error.message);
  }
}

TypeScript Support

The SDK is built with TypeScript and provides comprehensive type definitions:

import { 
  SuperSettingsClient,
  GlobalSetting,
  CreateUserSettingRequest,
  CascadeSettingResponse 
} from 'supersettings-sdk';

const client = new SuperSettingsClient({
  baseURL: 'https://api.supersettings.com',
  auth: { type: 'bearer', token: 'token' }
});

// Type-safe API calls
const settings: GlobalSetting[] = await client.listGlobalSettings();
const cascadeResult: CascadeSettingResponse = await client.getSetting('theme');

// Type-safe request objects
const userSettingData: CreateUserSettingRequest = {
  userId: 'user123',
  settingKey: 'preference',
  settingValue: { theme: 'dark', language: 'en' },
  description: 'User preferences'
};

Utility Methods

// Test connection
const isConnected = await client.testConnection();

// Update configuration
client.updateConfig({
  timeout: 20000,
  retryAttempts: 5
});

// Get current configuration (excluding sensitive auth data)
const config = client.getConfig();

Browser Usage

The SDK works seamlessly in browsers. You can use it with any bundler (Webpack, Rollup, Vite, etc.):

<!-- Via CDN (if published) -->
<script src="https://unpkg.com/supersettings-sdk"></script>
<script>
  const client = new SuperSettingsSDK.SuperSettingsClient({
    baseURL: 'https://api.supersettings.com',
    auth: { type: 'bearer', token: 'your-token' }
  });
</script>

API Reference

Client Methods

Cascade Resolution

• getSetting(settingKey, options) - Get setting with cascade resolution

Global Settings

• createOrUpdateGlobalSetting(data) - Create or update global setting
• listGlobalSettings(options) - List all global settings
• getGlobalSetting(id) - Get global setting by ID
• updateGlobalSetting(id, data) - Update global setting
• deleteGlobalSetting(id) - Delete global setting

Client Settings

• getAllClientSettings(clientId) - Get all client settings
• getClientSetting(clientId, settingKey) - Get specific client setting
• createClientSetting(data) - Create client setting
• updateClientSetting(id, data) - Update client setting
• deleteClientSetting(id) - Delete client setting

User Settings

• getAllUserSettings(userId) - Get all user settings
• getUserSetting(userId, settingKey) - Get specific user setting
• createUserSetting(data) - Create user setting
• updateUserSetting(id, data) - Update user setting
• deleteUserSetting(id) - Delete user setting

Dynamic Settings

• getAllDynamicSettings(uniqueId) - Get all dynamic settings
• getDynamicSetting(uniqueId, settingKey) - Get specific dynamic setting
• createDynamicSetting(data) - Create dynamic setting
• updateDynamicSetting(id, data) - Update dynamic setting
• deleteDynamicSetting(id) - Delete dynamic setting

Utility

• testConnection() - Test API connection
• updateConfig(newConfig) - Update client configuration
• getConfig() - Get current configuration

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For issues and questions, please open an issue on the GitHub repository.