bluesky-social · devinivy · Oct 5, 2023 · Oct 6, 2023 · Oct 6, 2023 · Oct 6, 2023
diff --git a/.github/workflows/build-and-push-pds-aws.yaml b/.github/workflows/build-and-push-pds-aws.yaml
@@ -3,6 +3,7 @@ on:
   push:
     branches:
       - main
+      - multi-pds-auth
 env:
   REGISTRY: ${{ secrets.AWS_ECR_REGISTRY_USEAST2_PACKAGES_REGISTRY }}
   USERNAME: ${{ secrets.AWS_ECR_REGISTRY_USEAST2_PACKAGES_USERNAME }}

diff --git a/lexicons/app/bsky/actor/defs.json b/lexicons/app/bsky/actor/defs.json
@@ -1,7 +1,6 @@
 {
   "lexicon": 1,
   "id": "app.bsky.actor.defs",
-  "description": "A reference to an actor in the network.",
   "defs": {
     "profileViewBasic": {
       "type": "object",
@@ -78,6 +77,7 @@
     },
     "viewerState": {
       "type": "object",
+      "description": "Metadata about the requesting account's relationship with the subject account. Only has meaningful content for authed requests.",
       "properties": {
         "muted": { "type": "boolean" },
         "mutedByList": {
@@ -104,7 +104,8 @@
           "#savedFeedsPref",
           "#personalDetailsPref",
           "#feedViewPref",
-          "#threadViewPref"
+          "#threadViewPref",
+          "#interestsPref"
         ]
       }
     },
@@ -143,6 +144,9 @@
             "type": "string",
             "format": "at-uri"
           }
+        },
+        "timelineIndex": {
+          "type": "integer"
         }
       }
     },
@@ -199,6 +203,18 @@
           "description": "Show followed users at the top of all replies."
         }
       }
+    },
+    "interestsPref": {
+      "type": "object",
+      "required": ["tags"],
+      "properties": {
+        "tags": {
+          "type": "array",
+          "maxLength": 100,
+          "items": { "type": "string", "maxLength": 640, "maxGraphemes": 64 },
+          "description": "A list of tags which describe the account owner's interests gathered during onboarding."
+        }
+      }
     }
   }
 }
diff --git a/lexicons/app/bsky/actor/getPreferences.json b/lexicons/app/bsky/actor/getPreferences.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get private preferences attached to the account.",
+      "description": "Get private preferences attached to the current account. Expected use is synchronization between multiple devices, and import/export during account migration. Requires auth.",
       "parameters": {
         "type": "params",
         "properties": {}

diff --git a/lexicons/app/bsky/actor/getProfile.json b/lexicons/app/bsky/actor/getProfile.json
@@ -4,12 +4,16 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get detailed profile view of an actor.",
+      "description": "Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth.",
       "parameters": {
         "type": "params",
         "required": ["actor"],
         "properties": {
-          "actor": { "type": "string", "format": "at-identifier" }
+          "actor": {
+            "type": "string",
+            "format": "at-identifier",
+            "description": "Handle or DID of account to fetch profile of."
+          }
         }
       },
       "output": {

diff --git a/lexicons/app/bsky/actor/getSuggestions.json b/lexicons/app/bsky/actor/getSuggestions.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a list of suggested actors, used for discovery.",
+      "description": "Get a list of suggested actors. Expected use is discovery of accounts to follow during new account onboarding.",
       "parameters": {
         "type": "params",
         "properties": {

diff --git a/lexicons/app/bsky/actor/profile.json b/lexicons/app/bsky/actor/profile.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "record",
-      "description": "A declaration of a profile.",
+      "description": "A declaration of a Bluesky account profile.",
       "key": "literal:self",
       "record": {
         "type": "object",
@@ -16,21 +16,25 @@
           },
           "description": {
             "type": "string",
+            "description": "Free-form profile description text.",
             "maxGraphemes": 256,
             "maxLength": 2560
           },
           "avatar": {
             "type": "blob",
+            "description": "Small image to be displayed next to posts from account. AKA, 'profile picture'",
             "accept": ["image/png", "image/jpeg"],
             "maxSize": 1000000
           },
           "banner": {
             "type": "blob",
+            "description": "Larger horizontal image to display behind profile view.",
             "accept": ["image/png", "image/jpeg"],
             "maxSize": 1000000
           },
           "labels": {
             "type": "union",
+            "description": "Self-label values, specific to the Bluesky application, on the overall account.",
             "refs": ["com.atproto.label.defs#selfLabels"]
           }
         }

diff --git a/lexicons/app/bsky/actor/searchActors.json b/lexicons/app/bsky/actor/searchActors.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Find actors (profiles) matching search criteria.",
+      "description": "Find actors (profiles) matching search criteria. Does not require auth.",
       "parameters": {
         "type": "params",
         "properties": {

diff --git a/lexicons/app/bsky/actor/searchActorsTypeahead.json b/lexicons/app/bsky/actor/searchActorsTypeahead.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Find actor suggestions for a prefix search term.",
+      "description": "Find actor suggestions for a prefix search term. Expected use is for auto-completion during text field entry. Does not require auth.",
       "parameters": {
         "type": "params",
         "properties": {

diff --git a/lexicons/app/bsky/embed/external.json b/lexicons/app/bsky/embed/external.json
@@ -1,10 +1,10 @@
 {
   "lexicon": 1,
   "id": "app.bsky.embed.external",
-  "description": "A representation of some externally linked content, embedded in another form of content.",
   "defs": {
     "main": {
       "type": "object",
+      "description": "A representation of some externally linked content (eg, a URL and 'card'), embedded in a Bluesky record (eg, a post).",
       "required": ["external"],
       "properties": {
         "external": {

diff --git a/lexicons/app/bsky/embed/images.json b/lexicons/app/bsky/embed/images.json
@@ -1,7 +1,7 @@
 {
   "lexicon": 1,
   "id": "app.bsky.embed.images",
-  "description": "A set of images embedded in some other form of content.",
+  "description": "A set of images embedded in a Bluesky record (eg, a post).",
   "defs": {
     "main": {
       "type": "object",
@@ -23,7 +23,10 @@
           "accept": ["image/*"],
           "maxSize": 1000000
         },
-        "alt": { "type": "string" },
+        "alt": {
+          "type": "string",
+          "description": "Alt text description of the image, for accessibility."
+        },
         "aspectRatio": { "type": "ref", "ref": "#aspectRatio" }
       }
     },
@@ -51,9 +54,18 @@
       "type": "object",
       "required": ["thumb", "fullsize", "alt"],
       "properties": {
-        "thumb": { "type": "string" },
-        "fullsize": { "type": "string" },
-        "alt": { "type": "string" },
+        "thumb": {
+          "type": "string",
+          "description": "Fully-qualified URL where a thumbnail of the image can be fetched. For example, CDN location provided by the App View."
+        },
+        "fullsize": {
+          "type": "string",
+          "description": "Fully-qualified URL where a large version of the image can be fetched. May or may not be the exact original blob. For example, CDN location provided by the App View."
+        },
+        "alt": {
+          "type": "string",
+          "description": "Alt text description of the image, for accessibility."
+        },
         "aspectRatio": { "type": "ref", "ref": "#aspectRatio" }
       }
     }

diff --git a/lexicons/app/bsky/embed/record.json b/lexicons/app/bsky/embed/record.json
@@ -1,7 +1,7 @@
 {
   "lexicon": 1,
   "id": "app.bsky.embed.record",
-  "description": "A representation of a record embedded in another form of content.",
+  "description": "A representation of a record embedded in a Bluesky record (eg, a post). For example, a quote-post, or sharing a feed generator record.",
   "defs": {
     "main": {
       "type": "object",
@@ -36,7 +36,10 @@
           "type": "ref",
           "ref": "app.bsky.actor.defs#profileViewBasic"
         },
-        "value": { "type": "unknown" },
+        "value": {
+          "type": "unknown",
+          "description": "The record data itself."
+        },
         "labels": {
           "type": "array",
           "items": { "type": "ref", "ref": "com.atproto.label.defs#label" }

diff --git a/lexicons/app/bsky/embed/recordWithMedia.json b/lexicons/app/bsky/embed/recordWithMedia.json
@@ -1,7 +1,7 @@
 {
   "lexicon": 1,
   "id": "app.bsky.embed.recordWithMedia",
-  "description": "A representation of a record embedded in another form of content, alongside other compatible embeds.",
+  "description": "A representation of a record embedded in a Bluesky record (eg, a post), alongside other compatible embeds. For example, a quote post and image, or a quote post and external URL card.",
   "defs": {
     "main": {
       "type": "object",

diff --git a/lexicons/app/bsky/feed/defs.json b/lexicons/app/bsky/feed/defs.json
@@ -36,6 +36,7 @@
     },
     "viewerState": {
       "type": "object",
+      "description": "Metadata about the requesting account's relationship with the subject content. Only has meaningful content for authed requests.",
       "properties": {
         "repost": { "type": "string", "format": "at-uri" },
         "like": { "type": "string", "format": "at-uri" },

diff --git a/lexicons/app/bsky/feed/describeFeedGenerator.json b/lexicons/app/bsky/feed/describeFeedGenerator.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get information about a feed generator, including policies and offered feed URIs.",
+      "description": "Get information about a feed generator, including policies and offered feed URIs. Does not require auth; implemented by Feed Generator services (not App View).",
       "output": {
         "encoding": "application/json",
         "schema": {

diff --git a/lexicons/app/bsky/feed/generator.json b/lexicons/app/bsky/feed/generator.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "record",
-      "description": "A declaration of the existence of a feed generator.",
+      "description": "Record declaring of the existence of a feed generator, and containing metadata about it. The record can exist in any repository.",
       "key": "any",
       "record": {
         "type": "object",
@@ -32,6 +32,7 @@
           },
           "labels": {
             "type": "union",
+            "description": "Self-label values",
             "refs": ["com.atproto.label.defs#selfLabels"]
           },
           "createdAt": { "type": "string", "format": "datetime" }

diff --git a/lexicons/app/bsky/feed/getActorFeeds.json b/lexicons/app/bsky/feed/getActorFeeds.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a list of feeds created by the actor.",
+      "description": "Get a list of feeds (feed generator records) created by the actor (in the actor's repo).",
       "parameters": {
         "type": "params",
         "required": ["actor"],

diff --git a/lexicons/app/bsky/feed/getActorLikes.json b/lexicons/app/bsky/feed/getActorLikes.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a list of posts liked by an actor.",
+      "description": "Get a list of posts liked by an actor. Does not require auth.",
       "parameters": {
         "type": "params",
         "required": ["actor"],

diff --git a/lexicons/app/bsky/feed/getAuthorFeed.json b/lexicons/app/bsky/feed/getAuthorFeed.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a view of an actor's feed.",
+      "description": "Get a view of an actor's 'author feed' (post and reposts by the author). Does not require auth.",
       "parameters": {
         "type": "params",
         "required": ["actor"],
@@ -19,10 +19,12 @@
           "cursor": { "type": "string" },
           "filter": {
             "type": "string",
+            "description": "Combinations of post/repost types to include in response.",
             "knownValues": [
               "posts_with_replies",
               "posts_no_replies",
-              "posts_with_media"
+              "posts_with_media",
+              "posts_and_author_threads"
             ],
             "default": "posts_with_replies"
           }

diff --git a/lexicons/app/bsky/feed/getFeed.json b/lexicons/app/bsky/feed/getFeed.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a hydrated feed from an actor's selected feed generator.",
+      "description": "Get a hydrated feed from an actor's selected feed generator. Implemented by App View.",
       "parameters": {
         "type": "params",
         "required": ["feed"],

diff --git a/lexicons/app/bsky/feed/getFeedGenerator.json b/lexicons/app/bsky/feed/getFeedGenerator.json
@@ -4,12 +4,16 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get information about a feed generator.",
+      "description": "Get information about a feed generator. Implemented by AppView.",
       "parameters": {
         "type": "params",
         "required": ["feed"],
         "properties": {
-          "feed": { "type": "string", "format": "at-uri" }
+          "feed": {
+            "type": "string",
+            "format": "at-uri",
+            "description": "AT-URI of the feed generator record."
+          }
         }
       },
       "output": {
@@ -22,8 +26,14 @@
               "type": "ref",
               "ref": "app.bsky.feed.defs#generatorView"
             },
-            "isOnline": { "type": "boolean" },
-            "isValid": { "type": "boolean" }
+            "isOnline": {
+              "type": "boolean",
+              "description": "Indicates whether the feed generator service has been online recently, or else seems to be inactive."
+            },
+            "isValid": {
+              "type": "boolean",
+              "description": "Indicates whether the feed generator service is compatible with the record declaration."
+            }
           }
         }
       }

diff --git a/lexicons/app/bsky/feed/getFeedSkeleton.json b/lexicons/app/bsky/feed/getFeedSkeleton.json
@@ -4,12 +4,16 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a skeleton of a feed provided by a feed generator.",
+      "description": "Get a skeleton of a feed provided by a feed generator. Auth is optional, depending on provider requirements, and provides the DID of the requester. Implemented by Feed Generator Service.",
       "parameters": {
         "type": "params",
         "required": ["feed"],
         "properties": {
-          "feed": { "type": "string", "format": "at-uri" },
+          "feed": {
+            "type": "string",
+            "format": "at-uri",
+            "description": "Reference to feed generator record describing the specific feed being requested."
+          },
           "limit": {
             "type": "integer",
             "minimum": 1,