✨ Ozone instance-wide and user-specific settings (bluesky-social#2905)

* ✨ Settings endpoints are working

* 🧹 Rename file

* ✨ Replace ad-hoc manage roles to match team member roles

* ♻️ Refactor role names

* ✨ Polish up

* ✨ Move to using id for pagination

* 📝 Add changeset

* ✅ Update snapshots

* ⚡ Change column order in setting table index and add did in all queries

.changeset/tender-needles-ring.md

@@ -0,0 +1,6 @@
+---
+"@atproto/ozone": patch
+"@atproto/api": patch
+---
+
+Add user specific and instance-wide settings api for ozone

lexicons/tools/ozone/setting/defs.json

@@ -0,0 +1,63 @@
+{
+  "lexicon": 1,
+  "id": "tools.ozone.setting.defs",
+  "defs": {
+    "option": {
+      "type": "object",
+      "required": [
+        "key",
+        "value",
+        "did",
+        "scope",
+        "createdBy",
+        "lastUpdatedBy"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "format": "nsid"
+        },
+        "did": {
+          "type": "string",
+          "format": "did"
+        },
+        "value": {
+          "type": "unknown"
+        },
+        "description": {
+          "type": "string",
+          "maxGraphemes": 1024,
+          "maxLength": 10240
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "datetime"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "datetime"
+        },
+        "managerRole": {
+          "type": "string",
+          "knownValues": [
+            "tools.ozone.team.defs#roleModerator",
+            "tools.ozone.team.defs#roleTriage",
+            "tools.ozone.team.defs#roleAdmin"
+          ]
+        },
+        "scope": {
+          "type": "string",
+          "knownValues": ["instance", "personal"]
+        },
+        "createdBy": {
+          "type": "string",
+          "format": "did"
+        },
+        "lastUpdatedBy": {
+          "type": "string",
+          "format": "did"
+        }
+      }
+    }
+  }
+}

lexicons/tools/ozone/setting/listOptions.json

@@ -0,0 +1,61 @@
+{
+  "lexicon": 1,
+  "id": "tools.ozone.setting.listOptions",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List settings with optional filtering",
+      "parameters": {
+        "type": "params",
+        "properties": {
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 50
+          },
+          "cursor": {
+            "type": "string"
+          },
+          "scope": {
+            "type": "string",
+            "knownValues": ["instance", "personal"],
+            "default": "instance"
+          },
+          "prefix": {
+            "type": "string",
+            "description": "Filter keys by prefix"
+          },
+          "keys": {
+            "type": "array",
+            "maxLength": 100,
+            "items": {
+              "type": "string",
+              "format": "nsid"
+            },
+            "description": "Filter for only the specified keys. Ignored if prefix is provided"
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["options"],
+          "properties": {
+            "cursor": {
+              "type": "string"
+            },
+            "options": {
+              "type": "array",
+              "items": {
+                "type": "ref",
+                "ref": "tools.ozone.setting.defs#option"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

lexicons/tools/ozone/setting/removeOptions.json

@@ -0,0 +1,39 @@
+{
+  "lexicon": 1,
+  "id": "tools.ozone.setting.removeOptions",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Delete settings by key",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["keys", "scope"],
+          "properties": {
+            "keys": {
+              "type": "array",
+              "minLength": 1,
+              "maxLength": 200,
+              "items": {
+                "type": "string",
+                "format": "nsid"
+              }
+            },
+            "scope": {
+              "type": "string",
+              "knownValues": ["instance", "personal"]
+            }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {}
+        }
+      }
+    }
+  }
+}

lexicons/tools/ozone/setting/upsertOption.json

@@ -0,0 +1,55 @@
+{
+  "lexicon": 1,
+  "id": "tools.ozone.setting.upsertOption",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Create or update setting option",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["key", "scope", "value"],
+          "properties": {
+            "key": {
+              "type": "string",
+              "format": "nsid"
+            },
+            "scope": {
+              "type": "string",
+              "knownValues": ["instance", "personal"]
+            },
+            "value": {
+              "type": "unknown"
+            },
+            "description": {
+              "type": "string",
+              "maxLength": 2000
+            },
+            "managerRole": {
+              "type": "string",
+              "knownValues": [
+                "tools.ozone.team.defs#roleModerator",
+                "tools.ozone.team.defs#roleTriage",
+                "tools.ozone.team.defs#roleAdmin"
+              ]
+            }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["option"],
+          "properties": {
+            "option": {
+              "type": "ref",
+              "ref": "tools.ozone.setting.defs#option"
+            }
+          }
+        }
+      }
+    }
+  }
+}

packages/api/src/client/index.ts

@@ -214,6 +214,10 @@ import * as ToolsOzoneSetDeleteValues from './types/tools/ozone/set/deleteValues
 import * as ToolsOzoneSetGetValues from './types/tools/ozone/set/getValues'
 import * as ToolsOzoneSetQuerySets from './types/tools/ozone/set/querySets'
 import * as ToolsOzoneSetUpsertSet from './types/tools/ozone/set/upsertSet'
+import * as ToolsOzoneSettingDefs from './types/tools/ozone/setting/defs'
+import * as ToolsOzoneSettingListOptions from './types/tools/ozone/setting/listOptions'
+import * as ToolsOzoneSettingRemoveOptions from './types/tools/ozone/setting/removeOptions'
+import * as ToolsOzoneSettingUpsertOption from './types/tools/ozone/setting/upsertOption'
 import * as ToolsOzoneSignatureDefs from './types/tools/ozone/signature/defs'
 import * as ToolsOzoneSignatureFindCorrelation from './types/tools/ozone/signature/findCorrelation'
 import * as ToolsOzoneSignatureFindRelatedAccounts from './types/tools/ozone/signature/findRelatedAccounts'
@@ -434,6 +438,10 @@ export * as ToolsOzoneSetDeleteValues from './types/tools/ozone/set/deleteValues
 export * as ToolsOzoneSetGetValues from './types/tools/ozone/set/getValues'
 export * as ToolsOzoneSetQuerySets from './types/tools/ozone/set/querySets'
 export * as ToolsOzoneSetUpsertSet from './types/tools/ozone/set/upsertSet'
+export * as ToolsOzoneSettingDefs from './types/tools/ozone/setting/defs'
+export * as ToolsOzoneSettingListOptions from './types/tools/ozone/setting/listOptions'
+export * as ToolsOzoneSettingRemoveOptions from './types/tools/ozone/setting/removeOptions'
+export * as ToolsOzoneSettingUpsertOption from './types/tools/ozone/setting/upsertOption'
 export * as ToolsOzoneSignatureDefs from './types/tools/ozone/signature/defs'
 export * as ToolsOzoneSignatureFindCorrelation from './types/tools/ozone/signature/findCorrelation'
 export * as ToolsOzoneSignatureFindRelatedAccounts from './types/tools/ozone/signature/findRelatedAccounts'
@@ -3433,6 +3441,7 @@ export class ToolsOzoneNS {
   moderation: ToolsOzoneModerationNS
   server: ToolsOzoneServerNS
   set: ToolsOzoneSetNS
+  setting: ToolsOzoneSettingNS
   signature: ToolsOzoneSignatureNS
   team: ToolsOzoneTeamNS
 
@@ -3442,6 +3451,7 @@ export class ToolsOzoneNS {
     this.moderation = new ToolsOzoneModerationNS(client)
     this.server = new ToolsOzoneServerNS(client)
     this.set = new ToolsOzoneSetNS(client)
+    this.setting = new ToolsOzoneSettingNS(client)
     this.signature = new ToolsOzoneSignatureNS(client)
     this.team = new ToolsOzoneTeamNS(client)
   }
@@ -3701,6 +3711,50 @@ export class ToolsOzoneSetNS {
   }
 }
 
+export class ToolsOzoneSettingNS {
+  _client: XrpcClient
+
+  constructor(client: XrpcClient) {
+    this._client = client
+  }
+
+  listOptions(
+    params?: ToolsOzoneSettingListOptions.QueryParams,
+    opts?: ToolsOzoneSettingListOptions.CallOptions,
+  ): Promise<ToolsOzoneSettingListOptions.Response> {
+    return this._client.call(
+      'tools.ozone.setting.listOptions',
+      params,
+      undefined,
+      opts,
+    )
+  }
+
+  removeOptions(
+    data?: ToolsOzoneSettingRemoveOptions.InputSchema,
+    opts?: ToolsOzoneSettingRemoveOptions.CallOptions,
+  ): Promise<ToolsOzoneSettingRemoveOptions.Response> {
+    return this._client.call(
+      'tools.ozone.setting.removeOptions',
+      opts?.qp,
+      data,
+      opts,
+    )
+  }
+
+  upsertOption(
+    data?: ToolsOzoneSettingUpsertOption.InputSchema,
+    opts?: ToolsOzoneSettingUpsertOption.CallOptions,
+  ): Promise<ToolsOzoneSettingUpsertOption.Response> {
+    return this._client.call(
+      'tools.ozone.setting.upsertOption',
+      opts?.qp,
+      data,
+      opts,
+    )
+  }
+}
+
 export class ToolsOzoneSignatureNS {
   _client: XrpcClient