Settings API (Pending)

Migration Pending

This API is pending migration to Cloudflare Workers.

The Settings API manages system configuration, feature flags, and organizational settings.

Planned Procedures

Procedure	Type	Description
settings.getAll	Query	Get all settings
settings.getByCategory	Query	Get settings by category
settings.update	Mutation	Update setting value
settings.reset	Mutation	Reset to defaults
settings.getFeatureFlags	Query	Get feature flags
settings.updateFeatureFlag	Mutation	Toggle feature
settings.getNotifications	Query	Get notification settings
settings.updateNotifications	Mutation	Update notifications

Data Model

Setting

interface Setting {
  id: string;
  key: string;
  value: any;
  type: SettingType;
  category: SettingCategory;
  label: string;
  description?: string;
  isPublic: boolean;
  isEditable: boolean;
  defaultValue: any;
  validation?: SettingValidation;
  updatedAt: Date;
  updatedBy?: string;
}

Setting Type

enum SettingType {
  STRING = "STRING",
  NUMBER = "NUMBER",
  BOOLEAN = "BOOLEAN",
  JSON = "JSON",
  SELECT = "SELECT",
  MULTI_SELECT = "MULTI_SELECT"
}

Setting Category

enum SettingCategory {
  GENERAL = "GENERAL",
  SECURITY = "SECURITY",
  NOTIFICATIONS = "NOTIFICATIONS",
  APPEARANCE = "APPEARANCE",
  INTEGRATIONS = "INTEGRATIONS",
  ADVANCED = "ADVANCED"
}

Settings Categories

General Settings

Key	Type	Default	Description
app.name	String	"Smart City TVMS"	Application name
app.logo	String	null	Custom logo URL
app.language	Select	"en"	Default language
app.timezone	String	"Asia/Almaty"	System timezone
app.dateFormat	Select	"DD/MM/YYYY"	Date format
app.timeFormat	Select	"24h"	Time format

Security Settings

Key	Type	Default	Description
security.sessionTimeout	Number	24	Session timeout (hours)
security.maxLoginAttempts	Number	5	Max failed logins
security.lockoutDuration	Number	30	Lockout time (minutes)
security.passwordExpiry	Number	90	Password expiry (days)
security.mfaEnabled	Boolean	false	Require MFA
security.ipWhitelist	JSON	[]	Allowed IP ranges

Notification Settings

Key	Type	Default	Description
notify.email.enabled	Boolean	true	Email notifications
notify.email.smtp	JSON	{}	SMTP configuration
notify.sms.enabled	Boolean	false	SMS notifications
notify.sms.provider	Select	null	SMS provider
notify.webhook.enabled	Boolean	false	Webhook notifications
notify.webhook.url	String	null	Webhook endpoint

Integration Settings

Key	Type	Default	Description
integration.mapbox.token	String	null	Mapbox API token
integration.analytics.enabled	Boolean	true	Analytics tracking
integration.api.rateLimit	Number	1000	API rate limit/hour
integration.export.formats	MultiSelect	["PDF","CSV"]	Export formats

Planned Input Schemas

Update Setting

{
  key: string;                 // Setting key
  value: any;                  // New value
}

Update Multiple Settings

{
  settings: Array<{
    key: string;
    value: any;
  }>;
}

Get Settings by Category

{
  category: SettingCategory;
  includePrivate?: boolean;    // Admin only
}

Expected Responses

Get All Settings

{
  "settings": [
    {
      "key": "app.name",
      "value": "Smart City TVMS",
      "type": "STRING",
      "category": "GENERAL",
      "label": "Application Name",
      "description": "Name displayed in the header",
      "isPublic": true,
      "isEditable": true
    },
    {
      "key": "security.sessionTimeout",
      "value": 24,
      "type": "NUMBER",
      "category": "SECURITY",
      "label": "Session Timeout",
      "description": "Hours until session expires",
      "isPublic": false,
      "isEditable": true,
      "validation": {
        "min": 1,
        "max": 168
      }
    }
  ],
  "categories": ["GENERAL", "SECURITY", "NOTIFICATIONS", "APPEARANCE"]
}

Get Feature Flags

{
  "features": {
    "dashboard": {
      "enabled": true,
      "description": "Main dashboard"
    },
    "sensors": {
      "enabled": true,
      "description": "Sensor management"
    },
    "reports": {
      "enabled": true,
      "description": "Reports and analytics"
    },
    "incidents": {
      "enabled": true,
      "description": "Incident management"
    },
    "realtime": {
      "enabled": true,
      "description": "Real-time updates"
    },
    "aiAnalytics": {
      "enabled": false,
      "description": "AI-powered analytics (beta)"
    }
  }
}

Validation Rules

String Validation

{
  minLength?: number;
  maxLength?: number;
  pattern?: string;            // Regex pattern
}

Number Validation

{
  min?: number;
  max?: number;
  step?: number;
}

Select Validation

{
  options: Array<{
    value: string;
    label: string;
  }>;
}

D1 Schema

CREATE TABLE settings (
  id TEXT PRIMARY KEY,
  key TEXT UNIQUE NOT NULL,
  value TEXT NOT NULL,
  type TEXT NOT NULL,
  category TEXT NOT NULL,
  label TEXT NOT NULL,
  description TEXT,
  isPublic INTEGER DEFAULT 1,
  isEditable INTEGER DEFAULT 1,
  defaultValue TEXT,
  validation TEXT,
  updatedAt TEXT NOT NULL,
  updatedBy TEXT,
  FOREIGN KEY (updatedBy) REFERENCES User(id)
);

CREATE INDEX idx_settings_key ON settings(key);
CREATE INDEX idx_settings_category ON settings(category);

-- Feature flags
CREATE TABLE feature_flags (
  id TEXT PRIMARY KEY,
  key TEXT UNIQUE NOT NULL,
  enabled INTEGER DEFAULT 0,
  description TEXT,
  metadata TEXT,
  updatedAt TEXT NOT NULL
);

Default Settings Initialization

On first deployment, seed default settings:

const defaultSettings = [
  {
    key: 'app.name',
    value: 'Smart City TVMS',
    type: 'STRING',
    category: 'GENERAL',
    label: 'Application Name',
    isPublic: true,
  },
  {
    key: 'app.timezone',
    value: 'Asia/Almaty',
    type: 'STRING',
    category: 'GENERAL',
    label: 'System Timezone',
    isPublic: true,
  },
  // ... more defaults
];

Related APIs

• System - Current system settings
• Users - User-specific settings
• Authentication - Security settings impact