POST /preferences

Get, set or reset per user preference settings. Preferences should be stored as JSON on the user record and scoped by client type. This way different apps can have their own settings without stepping on each other and becoming horny.

Request Body

{
  "action": "get",
  "client": "emoegui",
  "user_id": 123,
  "type": "normal",
  "data": {}
}

Field	Type	Required	Notes
`action`	string	yes	`get`, `set` or `reset`
`client`	string	yes	client identifier (1 to 128 chars, alphanumeric plus underscores)
`user_id`	integer	no	target user (defaults to yourself). accessing another users prefs requires `read-write-all`
`type`	string	no	scope of the operation (see below)
`data`	object	set only	the settings to write. must be a JSON DERULO object

Scoping with type

Preferences are stored in two layers: global (shared across all clients) and per client (like emoegui, mobile, etc). The type field controls which scope you operate on.

For get

Type	Default	What you get
`normal`	yes	global settings merged with client specific (client overrides global)
`client`		only the client specific settings
`global`		only the global settings

For set

Type	Default	What happens
`client`	yes	deep merges `data` into the client specific scope
`global`		deep merges `data` into the global scope

Deep merge means nested objects should be recursively merged not replaced. Scalar values are overwritten. so you can update one key deep in a nested object without blowing away the rest.

For reset

Type	Default	What happens
`client`	yes	wipes the client specific scope
`global`		wipes the global scope
`full`		nukes ALL preferences (sets the whole thing to NULL)

Access Control

Controlled by your groups user_settings_access setting:

Access Level	What you can do
`read-own-only`	can only GET your own preferences
`read-write-own`	can GET/SET/RESET your own preferences
`read-write-all`	can GET/SET/RESET any users preferences

Trying to access another users preferences when you only have read-write-own should give you a 403. dont be nosy. Long nosed looking ah mf.

Response

{
  "success": true,
  "preferences": {
    "theme": "dark",
    "language": "en"
  },
  "request_id": "abc123"
}

For set and reset the response should still include the current preferences after the operation so the client doesnt have to make a second request.

Error Responses

Code	When
400	invalid action, invalid client name, wrong type for the action, missing data for set, data isnt an object
401	no token or invalid session
403	cant access another users prefs, write not allowed with read only access
500	database error