diff --git a/lexicons/app/bsky/actor/defs.json b/lexicons/app/bsky/actor/defs.json index 9f8e2ea97c8..fa3772c4ff3 100644 --- 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": { @@ -144,6 +144,9 @@ "type": "string", "format": "at-uri" } + }, + "timelineIndex": { + "type": "integer" } } }, diff --git a/lexicons/app/bsky/actor/getPreferences.json b/lexicons/app/bsky/actor/getPreferences.json index cbd6b60bd6a..e6356a86f47 100644 --- 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 index 1bb2ad2fea1..15b0fcc2ec0 100644 --- 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 index 74465dfdf2e..2004ae6f23e 100644 --- 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 index e1b7c6a2b96..feb083d500a 100644 --- 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 index 48fbacf4fcc..15ccb082238 100644 --- 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 index 495b7081c38..4e3cb1b4e88 100644 --- 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 index 8946382835f..b9c8c1596d5 100644 --- 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 index 5baa7ab3f74..307607bb7c2 100644 --- 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 index 4b3d4f814a5..fff9730237d 100644 --- 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 index 9bc5fe09048..46145464fe2 100644 --- 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 index 15a7cb7a719..7f121e88403 100644 --- 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 index f95027183a1..0c7b8c8638e 100644 --- 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 index 8c00884ad28..d0e361b72cb 100644 --- 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 index a0620477bc3..9a7dae0ad5d 100644 --- 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 index b3baa58a457..22f8ed984ac 100644 --- 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 index 1939fa9a49d..90e4d1a7708 100644 --- 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,6 +19,7 @@ "cursor": { "type": "string" }, "filter": { "type": "string", + "description": "Combinations of post/repost types to include in response.", "knownValues": [ "posts_with_replies", "posts_no_replies", diff --git a/lexicons/app/bsky/feed/getFeed.json b/lexicons/app/bsky/feed/getFeed.json index 84407bde155..ada3098b56f 100644 --- 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 index 8b3d4d0551a..190eca85b26 100644 --- 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 index 03f3ba04c0f..2bcaa13d4f0 100644 --- 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, diff --git a/lexicons/app/bsky/feed/getLikes.json b/lexicons/app/bsky/feed/getLikes.json index ffcbc01ac53..d2c5b1a77df 100644 --- a/lexicons/app/bsky/feed/getLikes.json +++ b/lexicons/app/bsky/feed/getLikes.json @@ -4,13 +4,21 @@ "defs": { "main": { "type": "query", - "description": "Get the list of likes.", + "description": "Get like records which reference a subject (by AT-URI and CID).", "parameters": { "type": "params", "required": ["uri"], "properties": { - "uri": { "type": "string", "format": "at-uri" }, - "cid": { "type": "string", "format": "cid" }, + "uri": { + "type": "string", + "format": "at-uri", + "description": "AT-URI of the subject (eg, a post record)." + }, + "cid": { + "type": "string", + "format": "cid", + "description": "CID of the subject record (aka, specific version of record), to filter likes." + }, "limit": { "type": "integer", "minimum": 1, diff --git a/lexicons/app/bsky/feed/getListFeed.json b/lexicons/app/bsky/feed/getListFeed.json index 4c5358fcfd7..9dd9fdc70f3 100644 --- a/lexicons/app/bsky/feed/getListFeed.json +++ b/lexicons/app/bsky/feed/getListFeed.json @@ -4,12 +4,16 @@ "defs": { "main": { "type": "query", - "description": "Get a view of a recent posts from actors in a list.", + "description": "Get a feed of recent posts from a list (posts and reposts from any actors on the list). Does not require auth.", "parameters": { "type": "params", "required": ["list"], "properties": { - "list": { "type": "string", "format": "at-uri" }, + "list": { + "type": "string", + "format": "at-uri", + "description": "Reference (AT-URI) to the list record." + }, "limit": { "type": "integer", "minimum": 1, diff --git a/lexicons/app/bsky/feed/getPostThread.json b/lexicons/app/bsky/feed/getPostThread.json index b983617041f..89e99d9c6d7 100644 --- a/lexicons/app/bsky/feed/getPostThread.json +++ b/lexicons/app/bsky/feed/getPostThread.json @@ -4,20 +4,26 @@ "defs": { "main": { "type": "query", - "description": "Get posts in a thread.", + "description": "Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.", "parameters": { "type": "params", "required": ["uri"], "properties": { - "uri": { "type": "string", "format": "at-uri" }, + "uri": { + "type": "string", + "format": "at-uri", + "description": "Reference (AT-URI) to post record." + }, "depth": { "type": "integer", + "description": "How many levels of reply depth should be included in response.", "default": 6, "minimum": 0, "maximum": 1000 }, "parentHeight": { "type": "integer", + "description": "How many levels of parent (and grandparent, etc) post to include.", "default": 80, "minimum": 0, "maximum": 1000 diff --git a/lexicons/app/bsky/feed/getPosts.json b/lexicons/app/bsky/feed/getPosts.json index c985a5cf033..e555ee16326 100644 --- a/lexicons/app/bsky/feed/getPosts.json +++ b/lexicons/app/bsky/feed/getPosts.json @@ -4,13 +4,14 @@ "defs": { "main": { "type": "query", - "description": "Get a view of an actor's feed.", + "description": "Gets post views for a specified list of posts (by AT-URI). This is sometimes referred to as 'hydrating' a 'feed skeleton'.", "parameters": { "type": "params", "required": ["uris"], "properties": { "uris": { "type": "array", + "description": "List of post AT-URIs to return hydrated views for.", "items": { "type": "string", "format": "at-uri" }, "maxLength": 25 } diff --git a/lexicons/app/bsky/feed/getRepostedBy.json b/lexicons/app/bsky/feed/getRepostedBy.json index 99abc6d5cde..db39534658b 100644 --- a/lexicons/app/bsky/feed/getRepostedBy.json +++ b/lexicons/app/bsky/feed/getRepostedBy.json @@ -4,13 +4,21 @@ "defs": { "main": { "type": "query", - "description": "Get a list of reposts.", + "description": "Get a list of reposts for a given post.", "parameters": { "type": "params", "required": ["uri"], "properties": { - "uri": { "type": "string", "format": "at-uri" }, - "cid": { "type": "string", "format": "cid" }, + "uri": { + "type": "string", + "format": "at-uri", + "description": "Reference (AT-URI) of post record" + }, + "cid": { + "type": "string", + "format": "cid", + "description": "If supplied, filters to reposts of specific version (by CID) of the post record." + }, "limit": { "type": "integer", "minimum": 1, diff --git a/lexicons/app/bsky/feed/getSuggestedFeeds.json b/lexicons/app/bsky/feed/getSuggestedFeeds.json index de7c4fef753..e643d3391e5 100644 --- a/lexicons/app/bsky/feed/getSuggestedFeeds.json +++ b/lexicons/app/bsky/feed/getSuggestedFeeds.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get a list of suggested feeds for the viewer.", + "description": "Get a list of suggested feeds (feed generators) for the requesting account.", "parameters": { "type": "params", "properties": { diff --git a/lexicons/app/bsky/feed/getTimeline.json b/lexicons/app/bsky/feed/getTimeline.json index c3b116381c6..816380fe680 100644 --- a/lexicons/app/bsky/feed/getTimeline.json +++ b/lexicons/app/bsky/feed/getTimeline.json @@ -4,11 +4,14 @@ "defs": { "main": { "type": "query", - "description": "Get a view of the actor's home timeline.", + "description": "Get a view of the requesting account's home timeline. This is expected to be some form of reverse-chronological feed.", "parameters": { "type": "params", "properties": { - "algorithm": { "type": "string" }, + "algorithm": { + "type": "string", + "description": "Variant 'algorithm' for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism." + }, "limit": { "type": "integer", "minimum": 1, diff --git a/lexicons/app/bsky/feed/like.json b/lexicons/app/bsky/feed/like.json index d82f93bbb1b..c0de3b71e92 100644 --- a/lexicons/app/bsky/feed/like.json +++ b/lexicons/app/bsky/feed/like.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "record", - "description": "A declaration of a like.", + "description": "Record declaring a 'like' of a piece of subject content.", "key": "tid", "record": { "type": "object", diff --git a/lexicons/app/bsky/feed/post.json b/lexicons/app/bsky/feed/post.json index d5f92969253..b9b236b4f81 100644 --- a/lexicons/app/bsky/feed/post.json +++ b/lexicons/app/bsky/feed/post.json @@ -4,20 +4,26 @@ "defs": { "main": { "type": "record", - "description": "A declaration of a post.", + "description": "Record containing a Bluesky post.", "key": "tid", "record": { "type": "object", "required": ["text", "createdAt"], "properties": { - "text": { "type": "string", "maxLength": 3000, "maxGraphemes": 300 }, + "text": { + "type": "string", + "maxLength": 3000, + "maxGraphemes": 300, + "description": "The primary post content. May be an empty string, if there are embeds." + }, "entities": { "type": "array", - "description": "Deprecated: replaced by app.bsky.richtext.facet.", + "description": "DEPRECATED: replaced by app.bsky.richtext.facet.", "items": { "type": "ref", "ref": "#entity" } }, "facets": { "type": "array", + "description": "Annotations of text (mentions, URLs, hashtags, etc)", "items": { "type": "ref", "ref": "app.bsky.richtext.facet" } }, "reply": { "type": "ref", "ref": "#replyRef" }, @@ -32,20 +38,26 @@ }, "langs": { "type": "array", + "description": "Indicates human language of post primary text content.", "maxLength": 3, "items": { "type": "string", "format": "language" } }, "labels": { "type": "union", + "description": "Self-label values for this post. Effectively content warnings.", "refs": ["com.atproto.label.defs#selfLabels"] }, "tags": { "type": "array", + "description": "Additional hashtags, in addition to any included in post text and facets.", "maxLength": 8, - "items": { "type": "string", "maxLength": 640, "maxGraphemes": 64 }, - "description": "Additional non-inline tags describing this post." + "items": { "type": "string", "maxLength": 640, "maxGraphemes": 64 } }, - "createdAt": { "type": "string", "format": "datetime" } + "createdAt": { + "type": "string", + "format": "datetime", + "description": "Client-declared timestamp when this post was originally created." + } } } }, diff --git a/lexicons/app/bsky/feed/repost.json b/lexicons/app/bsky/feed/repost.json index 4dbef10b319..028fd627152 100644 --- a/lexicons/app/bsky/feed/repost.json +++ b/lexicons/app/bsky/feed/repost.json @@ -3,7 +3,7 @@ "id": "app.bsky.feed.repost", "defs": { "main": { - "description": "A declaration of a repost.", + "description": "Record representing a 'repost' of an existing Bluesky post.", "type": "record", "key": "tid", "record": { diff --git a/lexicons/app/bsky/feed/searchPosts.json b/lexicons/app/bsky/feed/searchPosts.json index a3e0bc47f03..c89655dd9db 100644 --- a/lexicons/app/bsky/feed/searchPosts.json +++ b/lexicons/app/bsky/feed/searchPosts.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Find posts matching search criteria.", + "description": "Find posts matching search criteria, returning views of those posts.", "parameters": { "type": "params", "required": ["q"], diff --git a/lexicons/app/bsky/feed/threadgate.json b/lexicons/app/bsky/feed/threadgate.json index 7969b6360a6..ff258da4d30 100644 --- a/lexicons/app/bsky/feed/threadgate.json +++ b/lexicons/app/bsky/feed/threadgate.json @@ -5,12 +5,16 @@ "main": { "type": "record", "key": "tid", - "description": "Defines interaction gating rules for a thread. The rkey of the threadgate record should match the rkey of the thread's root post.", + "description": "Record defining interaction gating rules for a thread (aka, reply controls). The record key (rkey) of the threadgate record must match the record key of the thread's root post, and that record must be in the same repository..", "record": { "type": "object", "required": ["post", "createdAt"], "properties": { - "post": { "type": "string", "format": "at-uri" }, + "post": { + "type": "string", + "format": "at-uri", + "description": "Reference (AT-URI) to the post record." + }, "allow": { "type": "array", "maxLength": 5, diff --git a/lexicons/app/bsky/graph/block.json b/lexicons/app/bsky/graph/block.json index 6231eb04e10..b64b11a956d 100644 --- a/lexicons/app/bsky/graph/block.json +++ b/lexicons/app/bsky/graph/block.json @@ -4,13 +4,17 @@ "defs": { "main": { "type": "record", - "description": "A declaration of a block.", + "description": "Record declaring a 'block' relationship against another account. NOTE: blocks are public in Bluesky; see blog posts for details.", "key": "tid", "record": { "type": "object", "required": ["subject", "createdAt"], "properties": { - "subject": { "type": "string", "format": "did" }, + "subject": { + "type": "string", + "format": "did", + "description": "DID of the account to be blocked." + }, "createdAt": { "type": "string", "format": "datetime" } } } diff --git a/lexicons/app/bsky/graph/follow.json b/lexicons/app/bsky/graph/follow.json index df4f4319d92..dd6347ac76d 100644 --- a/lexicons/app/bsky/graph/follow.json +++ b/lexicons/app/bsky/graph/follow.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "record", - "description": "A declaration of a social follow.", + "description": "Record declaring a social 'follow' relationship of another account. Duplicate follows will be ignored by the AppView.", "key": "tid", "record": { "type": "object", diff --git a/lexicons/app/bsky/graph/getBlocks.json b/lexicons/app/bsky/graph/getBlocks.json index bbfe956fbe0..79a28f66a52 100644 --- a/lexicons/app/bsky/graph/getBlocks.json +++ b/lexicons/app/bsky/graph/getBlocks.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get a list of who the actor is blocking.", + "description": "Enumerates which accounts the requesting account is currently blocking. Requires auth.", "parameters": { "type": "params", "properties": { diff --git a/lexicons/app/bsky/graph/getFollowers.json b/lexicons/app/bsky/graph/getFollowers.json index 378c7a7a339..a6c4facd653 100644 --- a/lexicons/app/bsky/graph/getFollowers.json +++ b/lexicons/app/bsky/graph/getFollowers.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get a list of an actor's followers.", + "description": "Enumerates accounts which follow a specified account (actor).", "parameters": { "type": "params", "required": ["actor"], diff --git a/lexicons/app/bsky/graph/getFollows.json b/lexicons/app/bsky/graph/getFollows.json index b90f7613889..81f1b6abe49 100644 --- a/lexicons/app/bsky/graph/getFollows.json +++ b/lexicons/app/bsky/graph/getFollows.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get a list of who the actor follows.", + "description": "Enumerates accounts which a specified account (actor) follows.", "parameters": { "type": "params", "required": ["actor"], diff --git a/lexicons/app/bsky/graph/getList.json b/lexicons/app/bsky/graph/getList.json index fd24668e5bd..cb95a003a56 100644 --- a/lexicons/app/bsky/graph/getList.json +++ b/lexicons/app/bsky/graph/getList.json @@ -4,12 +4,16 @@ "defs": { "main": { "type": "query", - "description": "Get a list of actors.", + "description": "Gets a 'view' (with additional context) of a specified list.", "parameters": { "type": "params", "required": ["list"], "properties": { - "list": { "type": "string", "format": "at-uri" }, + "list": { + "type": "string", + "format": "at-uri", + "description": "Reference (AT-URI) of the list record to hydrate." + }, "limit": { "type": "integer", "minimum": 1, diff --git a/lexicons/app/bsky/graph/getListBlocks.json b/lexicons/app/bsky/graph/getListBlocks.json index 9f9f59821f2..1bc976617ef 100644 --- a/lexicons/app/bsky/graph/getListBlocks.json +++ b/lexicons/app/bsky/graph/getListBlocks.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get lists that the actor is blocking.", + "description": "Get mod lists that the requesting account (actor) is blocking. Requires auth.", "parameters": { "type": "params", "properties": { diff --git a/lexicons/app/bsky/graph/getListMutes.json b/lexicons/app/bsky/graph/getListMutes.json index 8d42ac40f9c..a56a8257643 100644 --- a/lexicons/app/bsky/graph/getListMutes.json +++ b/lexicons/app/bsky/graph/getListMutes.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get lists that the actor is muting.", + "description": "Enumerates mod lists that the requesting account (actor) currently has muted. Requires auth.", "parameters": { "type": "params", "properties": { diff --git a/lexicons/app/bsky/graph/getLists.json b/lexicons/app/bsky/graph/getLists.json index 602dd15307d..127b13e5558 100644 --- a/lexicons/app/bsky/graph/getLists.json +++ b/lexicons/app/bsky/graph/getLists.json @@ -4,12 +4,16 @@ "defs": { "main": { "type": "query", - "description": "Get a list of lists that belong to an actor.", + "description": "Enumerates the lists created by a specified account (actor).", "parameters": { "type": "params", "required": ["actor"], "properties": { - "actor": { "type": "string", "format": "at-identifier" }, + "actor": { + "type": "string", + "format": "at-identifier", + "description": "The account (actor) to enumerate lists from." + }, "limit": { "type": "integer", "minimum": 1, diff --git a/lexicons/app/bsky/graph/getMutes.json b/lexicons/app/bsky/graph/getMutes.json index 8ceae00f607..22eaf0d384c 100644 --- a/lexicons/app/bsky/graph/getMutes.json +++ b/lexicons/app/bsky/graph/getMutes.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get a list of who the actor mutes.", + "description": "Enumerates accounts that the requesting account (actor) currently has muted. Requires auth.", "parameters": { "type": "params", "properties": { diff --git a/lexicons/app/bsky/graph/getRelationships.json b/lexicons/app/bsky/graph/getRelationships.json index ccd495dea7d..03490a25ec2 100644 --- a/lexicons/app/bsky/graph/getRelationships.json +++ b/lexicons/app/bsky/graph/getRelationships.json @@ -4,14 +4,19 @@ "defs": { "main": { "type": "query", - "description": "Enumerates public relationships between one account, and a list of other accounts", + "description": "Enumerates public relationships between one account, and a list of other accounts. Does not require auth.", "parameters": { "type": "params", "required": ["actor"], "properties": { - "actor": { "type": "string", "format": "at-identifier" }, + "actor": { + "type": "string", + "format": "at-identifier", + "description": "Primary account requesting relationships for." + }, "others": { "type": "array", + "description": "List of 'other' accounts to be related back to the primary.", "maxLength": 30, "items": { "type": "string", diff --git a/lexicons/app/bsky/graph/getSuggestedFollowsByActor.json b/lexicons/app/bsky/graph/getSuggestedFollowsByActor.json index 32873a537c9..5b0cfdebb70 100644 --- a/lexicons/app/bsky/graph/getSuggestedFollowsByActor.json +++ b/lexicons/app/bsky/graph/getSuggestedFollowsByActor.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get suggested follows related to a given actor.", + "description": "Enumerates follows similar to a given account (actor). Expected use is to recommend additional accounts immediately after following one account.", "parameters": { "type": "params", "required": ["actor"], diff --git a/lexicons/app/bsky/graph/list.json b/lexicons/app/bsky/graph/list.json index ccc845a6926..131114126d3 100644 --- a/lexicons/app/bsky/graph/list.json +++ b/lexicons/app/bsky/graph/list.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "record", - "description": "A declaration of a list of actors.", + "description": "Record representing a list of accounts (actors). Scope includes both moderation-oriented lists and curration-oriented lists.", "key": "tid", "record": { "type": "object", @@ -12,9 +12,15 @@ "properties": { "purpose": { "type": "ref", + "description": "Defines the purpose of the list (aka, moderation-oriented or curration-oriented)", "ref": "app.bsky.graph.defs#listPurpose" }, - "name": { "type": "string", "maxLength": 64, "minLength": 1 }, + "name": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "description": "Display name for list; can not be empty." + }, "description": { "type": "string", "maxGraphemes": 300, diff --git a/lexicons/app/bsky/graph/listblock.json b/lexicons/app/bsky/graph/listblock.json index b3a839c5316..df2e17f3c30 100644 --- a/lexicons/app/bsky/graph/listblock.json +++ b/lexicons/app/bsky/graph/listblock.json @@ -4,13 +4,17 @@ "defs": { "main": { "type": "record", - "description": "A block of an entire list of actors.", + "description": "Record representing a block relationship against an entire an entire list of accounts (actors).", "key": "tid", "record": { "type": "object", "required": ["subject", "createdAt"], "properties": { - "subject": { "type": "string", "format": "at-uri" }, + "subject": { + "type": "string", + "format": "at-uri", + "description": "Reference (AT-URI) to the mod list record." + }, "createdAt": { "type": "string", "format": "datetime" } } } diff --git a/lexicons/app/bsky/graph/listitem.json b/lexicons/app/bsky/graph/listitem.json index 2eafb1340be..adbd96e77da 100644 --- a/lexicons/app/bsky/graph/listitem.json +++ b/lexicons/app/bsky/graph/listitem.json @@ -4,14 +4,22 @@ "defs": { "main": { "type": "record", - "description": "An item under a declared list of actors.", + "description": "Record representing an account's inclusion on a specific list. The AppView will ignore duplicate listitem records.", "key": "tid", "record": { "type": "object", "required": ["subject", "list", "createdAt"], "properties": { - "subject": { "type": "string", "format": "did" }, - "list": { "type": "string", "format": "at-uri" }, + "subject": { + "type": "string", + "format": "did", + "description": "The account which is included on the list." + }, + "list": { + "type": "string", + "format": "at-uri", + "description": "Reference (AT-URI) to the list record (app.bsky.graph.list)." + }, "createdAt": { "type": "string", "format": "datetime" } } } diff --git a/lexicons/app/bsky/graph/muteActor.json b/lexicons/app/bsky/graph/muteActor.json index f1c3dd18f64..c2bf09a3b37 100644 --- a/lexicons/app/bsky/graph/muteActor.json +++ b/lexicons/app/bsky/graph/muteActor.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Mute an actor by DID or handle.", + "description": "Creates a mute relationship for the specified account. Mutes are private in Bluesky. Requires auth.", "input": { "encoding": "application/json", "schema": { diff --git a/lexicons/app/bsky/graph/muteActorList.json b/lexicons/app/bsky/graph/muteActorList.json index c75cc783c14..ad05e6349d7 100644 --- a/lexicons/app/bsky/graph/muteActorList.json +++ b/lexicons/app/bsky/graph/muteActorList.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Mute a list of actors.", + "description": "Creates a mute relationship for the specified list of accounts. Mutes are private in Bluesky. Requires auth.", "input": { "encoding": "application/json", "schema": { diff --git a/lexicons/app/bsky/graph/unmuteActor.json b/lexicons/app/bsky/graph/unmuteActor.json index 114af204890..bcea72db59d 100644 --- a/lexicons/app/bsky/graph/unmuteActor.json +++ b/lexicons/app/bsky/graph/unmuteActor.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Unmute an actor by DID or handle.", + "description": "Unmutes the specified account. Requires auth.", "input": { "encoding": "application/json", "schema": { diff --git a/lexicons/app/bsky/graph/unmuteActorList.json b/lexicons/app/bsky/graph/unmuteActorList.json index d9644cddc8e..a597838e112 100644 --- a/lexicons/app/bsky/graph/unmuteActorList.json +++ b/lexicons/app/bsky/graph/unmuteActorList.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Unmute a list of actors.", + "description": "Unmutes the specified list of accounts. Requires auth.", "input": { "encoding": "application/json", "schema": { diff --git a/lexicons/app/bsky/notification/getUnreadCount.json b/lexicons/app/bsky/notification/getUnreadCount.json index ab716b2a436..5eebbbf4eb5 100644 --- a/lexicons/app/bsky/notification/getUnreadCount.json +++ b/lexicons/app/bsky/notification/getUnreadCount.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get the count of unread notifications.", + "description": "Count the number of unread notifications for the requesting account. Requires auth.", "parameters": { "type": "params", "properties": { diff --git a/lexicons/app/bsky/notification/listNotifications.json b/lexicons/app/bsky/notification/listNotifications.json index ea74c5fba53..6c5095e1eb2 100644 --- a/lexicons/app/bsky/notification/listNotifications.json +++ b/lexicons/app/bsky/notification/listNotifications.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get a list of notifications.", + "description": "Enumerate notifications for the requesting account. Requires auth.", "parameters": { "type": "params", "properties": { diff --git a/lexicons/app/bsky/notification/registerPush.json b/lexicons/app/bsky/notification/registerPush.json index 80819ece46f..c4e50d1108c 100644 --- a/lexicons/app/bsky/notification/registerPush.json +++ b/lexicons/app/bsky/notification/registerPush.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Register for push notifications with a service.", + "description": "Register to receive push notifications, via a specified service, for the requesting account. Requires auth.", "input": { "encoding": "application/json", "schema": { diff --git a/lexicons/app/bsky/notification/updateSeen.json b/lexicons/app/bsky/notification/updateSeen.json index 33626343e51..84bb0e7d52f 100644 --- a/lexicons/app/bsky/notification/updateSeen.json +++ b/lexicons/app/bsky/notification/updateSeen.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Notify server that the user has seen notifications.", + "description": "Notify server that the requesting account has seen notifications. Requires auth.", "input": { "encoding": "application/json", "schema": { diff --git a/lexicons/app/bsky/richtext/facet.json b/lexicons/app/bsky/richtext/facet.json index ea8f2cba288..388a3a5e0ef 100644 --- a/lexicons/app/bsky/richtext/facet.json +++ b/lexicons/app/bsky/richtext/facet.json @@ -4,6 +4,7 @@ "defs": { "main": { "type": "object", + "description": "Annotation of a sub-string within rich text.", "required": ["index", "features"], "properties": { "index": { "type": "ref", "ref": "#byteSlice" }, @@ -15,7 +16,7 @@ }, "mention": { "type": "object", - "description": "A facet feature for actor mentions.", + "description": "Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID.", "required": ["did"], "properties": { "did": { "type": "string", "format": "did" } @@ -23,7 +24,7 @@ }, "link": { "type": "object", - "description": "A facet feature for links.", + "description": "Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.", "required": ["uri"], "properties": { "uri": { "type": "string", "format": "uri" } @@ -31,7 +32,7 @@ }, "tag": { "type": "object", - "description": "A hashtag.", + "description": "Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').", "required": ["tag"], "properties": { "tag": { "type": "string", "maxLength": 640, "maxGraphemes": 64 } @@ -39,7 +40,7 @@ }, "byteSlice": { "type": "object", - "description": "A text segment. Start is inclusive, end is exclusive. Indices are for utf8-encoded strings.", + "description": "Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.", "required": ["byteStart", "byteEnd"], "properties": { "byteStart": { "type": "integer", "minimum": 0 }, diff --git a/lexicons/com/atproto/admin/defs.json b/lexicons/com/atproto/admin/defs.json index 133deaf9383..e1315eb7473 100644 --- a/lexicons/com/atproto/admin/defs.json +++ b/lexicons/com/atproto/admin/defs.json @@ -185,6 +185,10 @@ "suspendUntil": { "type": "string", "format": "datetime" + }, + "tags": { + "type": "array", + "items": { "type": "string" } } } }, @@ -587,6 +591,27 @@ } } }, + "modEventTag": { + "type": "object", + "description": "Add/Remove a tag on a subject", + "required": ["add", "remove"], + "properties": { + "add": { + "type": "array", + "items": { "type": "string" }, + "description": "Tags to be added to the subject. If already exists, won't be duplicated." + }, + "remove": { + "type": "array", + "items": { "type": "string" }, + "description": "Tags to be removed to the subject. Ignores a tag If it doesn't exist, won't be duplicated." + }, + "comment": { + "type": "string", + "description": "Additional comment about added/removed tags." + } + } + }, "communicationTemplateView": { "type": "object", "required": [ diff --git a/lexicons/com/atproto/admin/emitModerationEvent.json b/lexicons/com/atproto/admin/emitModerationEvent.json index f32ad18461c..44ef72aad5b 100644 --- a/lexicons/com/atproto/admin/emitModerationEvent.json +++ b/lexicons/com/atproto/admin/emitModerationEvent.json @@ -23,7 +23,8 @@ "com.atproto.admin.defs#modEventMute", "com.atproto.admin.defs#modEventReverseTakedown", "com.atproto.admin.defs#modEventUnmute", - "com.atproto.admin.defs#modEventEmail" + "com.atproto.admin.defs#modEventEmail", + "com.atproto.admin.defs#modEventTag" ] }, "subject": { diff --git a/lexicons/com/atproto/admin/queryModerationEvents.json b/lexicons/com/atproto/admin/queryModerationEvents.json index 887921cfe20..239c17bd115 100644 --- a/lexicons/com/atproto/admin/queryModerationEvents.json +++ b/lexicons/com/atproto/admin/queryModerationEvents.json @@ -63,6 +63,16 @@ "items": { "type": "string" }, "description": "If specified, only events where all of these labels were removed are returned" }, + "addedTags": { + "type": "array", + "items": { "type": "string" }, + "description": "If specified, only events where all of these tags were added are returned" + }, + "removedTags": { + "type": "array", + "items": { "type": "string" }, + "description": "If specified, only events where all of these tags were removed are returned" + }, "reportTypes": { "type": "array", "items": { diff --git a/lexicons/com/atproto/admin/queryModerationStatuses.json b/lexicons/com/atproto/admin/queryModerationStatuses.json index e3e2a859bd2..5ac915ceef1 100644 --- a/lexicons/com/atproto/admin/queryModerationStatuses.json +++ b/lexicons/com/atproto/admin/queryModerationStatuses.json @@ -74,6 +74,14 @@ "maximum": 100, "default": 50 }, + "tags": { + "type": "array", + "items": { "type": "string" } + }, + "excludeTags": { + "type": "array", + "items": { "type": "string" } + }, "cursor": { "type": "string" } } }, diff --git a/lexicons/com/atproto/identity/resolveHandle.json b/lexicons/com/atproto/identity/resolveHandle.json index ae5aab8f8fc..95885088a7b 100644 --- a/lexicons/com/atproto/identity/resolveHandle.json +++ b/lexicons/com/atproto/identity/resolveHandle.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Provides the DID of a repo.", + "description": "Resolves a handle (domain name) to a DID.", "parameters": { "type": "params", "required": ["handle"], diff --git a/lexicons/com/atproto/identity/updateHandle.json b/lexicons/com/atproto/identity/updateHandle.json index 5fe392bb838..9bb5c347d38 100644 --- a/lexicons/com/atproto/identity/updateHandle.json +++ b/lexicons/com/atproto/identity/updateHandle.json @@ -4,14 +4,18 @@ "defs": { "main": { "type": "procedure", - "description": "Updates the handle of the account.", + "description": "Updates the current account's handle. Verifies handle validity, and updates did:plc document if necessary. Implemented by PDS, and requires auth.", "input": { "encoding": "application/json", "schema": { "type": "object", "required": ["handle"], "properties": { - "handle": { "type": "string", "format": "handle" } + "handle": { + "type": "string", + "format": "handle", + "description": "The new handle." + } } } } diff --git a/lexicons/com/atproto/label/queryLabels.json b/lexicons/com/atproto/label/queryLabels.json index 7b6fbe23d54..6c81cb0bba6 100644 --- a/lexicons/com/atproto/label/queryLabels.json +++ b/lexicons/com/atproto/label/queryLabels.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Find labels relevant to the provided URI patterns.", + "description": "Find labels relevant to the provided AT-URI patterns. Public endpoint for moderation services, though may return different or additional results with auth.", "parameters": { "type": "params", "required": ["uriPatterns"], diff --git a/lexicons/com/atproto/label/subscribeLabels.json b/lexicons/com/atproto/label/subscribeLabels.json index 9813ffc192e..5fb1a852d3d 100644 --- a/lexicons/com/atproto/label/subscribeLabels.json +++ b/lexicons/com/atproto/label/subscribeLabels.json @@ -4,13 +4,13 @@ "defs": { "main": { "type": "subscription", - "description": "Subscribe to label updates.", + "description": "Subscribe to stream of labels (and negations). Public endpoint implemented by mod services. Uses same sequencing scheme as repo event stream.", "parameters": { "type": "params", "properties": { "cursor": { "type": "integer", - "description": "The last known event to backfill from." + "description": "The last known event seq number to backfill from." } } }, diff --git a/lexicons/com/atproto/moderation/createReport.json b/lexicons/com/atproto/moderation/createReport.json index 161d622fcf2..f41d28d0b15 100644 --- a/lexicons/com/atproto/moderation/createReport.json +++ b/lexicons/com/atproto/moderation/createReport.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Report a repo or a record.", + "description": "Submit a moderation report regarding an atproto account or record. Implemented by moderation services (with PDS proxying), and requires auth.", "input": { "encoding": "application/json", "schema": { @@ -13,9 +13,13 @@ "properties": { "reasonType": { "type": "ref", + "description": "Indicates the broad category of violation the report is for.", "ref": "com.atproto.moderation.defs#reasonType" }, - "reason": { "type": "string" }, + "reason": { + "type": "string", + "description": "Additional context about the content and violation." + }, "subject": { "type": "union", "refs": [ diff --git a/lexicons/com/atproto/repo/applyWrites.json b/lexicons/com/atproto/repo/applyWrites.json index 050b6efbfab..427fc84c4a5 100644 --- a/lexicons/com/atproto/repo/applyWrites.json +++ b/lexicons/com/atproto/repo/applyWrites.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Apply a batch transaction of creates, updates, and deletes.", + "description": "Apply a batch transaction of repository creates, updates, and deletes. Requires auth, implemented by PDS.", "input": { "encoding": "application/json", "schema": { @@ -14,12 +14,12 @@ "repo": { "type": "string", "format": "at-identifier", - "description": "The handle or DID of the repo." + "description": "The handle or DID of the repo (aka, current account)." }, "validate": { "type": "boolean", "default": true, - "description": "Flag for validating the records." + "description": "Can be set to 'false' to skip Lexicon schema validation of record data, for all operations." }, "writes": { "type": "array", @@ -31,16 +31,22 @@ }, "swapCommit": { "type": "string", + "description": "If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations.", "format": "cid" } } } }, - "errors": [{ "name": "InvalidSwap" }] + "errors": [ + { + "name": "InvalidSwap", + "description": "Indicates that the 'swapCommit' parameter did not match current commit." + } + ] }, "create": { "type": "object", - "description": "Create a new record.", + "description": "Operation which creates a new record.", "required": ["collection", "value"], "properties": { "collection": { "type": "string", "format": "nsid" }, @@ -50,7 +56,7 @@ }, "update": { "type": "object", - "description": "Update an existing record.", + "description": "Operation which updates an existing record.", "required": ["collection", "rkey", "value"], "properties": { "collection": { "type": "string", "format": "nsid" }, @@ -60,7 +66,7 @@ }, "delete": { "type": "object", - "description": "Delete an existing record.", + "description": "Operation which deletes an existing record.", "required": ["collection", "rkey"], "properties": { "collection": { "type": "string", "format": "nsid" }, diff --git a/lexicons/com/atproto/repo/createRecord.json b/lexicons/com/atproto/repo/createRecord.json index baef20c88f0..185f5250850 100644 --- a/lexicons/com/atproto/repo/createRecord.json +++ b/lexicons/com/atproto/repo/createRecord.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Create a new record.", + "description": "Create a single new repository record. Requires auth, implemented by PDS.", "input": { "encoding": "application/json", "schema": { @@ -14,7 +14,7 @@ "repo": { "type": "string", "format": "at-identifier", - "description": "The handle or DID of the repo." + "description": "The handle or DID of the repo (aka, current account)." }, "collection": { "type": "string", @@ -23,17 +23,17 @@ }, "rkey": { "type": "string", - "description": "The key of the record.", + "description": "The Record Key.", "maxLength": 15 }, "validate": { "type": "boolean", "default": true, - "description": "Flag for validating the record." + "description": "Can be set to 'false' to skip Lexicon schema validation of record data." }, "record": { "type": "unknown", - "description": "The record to create." + "description": "The record itself. Must contain a $type field." }, "swapCommit": { "type": "string", @@ -54,7 +54,12 @@ } } }, - "errors": [{ "name": "InvalidSwap" }] + "errors": [ + { + "name": "InvalidSwap", + "description": "Indicates that 'swapCommit' didn't match current repo commit." + } + ] } } } diff --git a/lexicons/com/atproto/repo/deleteRecord.json b/lexicons/com/atproto/repo/deleteRecord.json index d8d7955b6a9..65b9f8f9536 100644 --- a/lexicons/com/atproto/repo/deleteRecord.json +++ b/lexicons/com/atproto/repo/deleteRecord.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Delete a record, or ensure it doesn't exist.", + "description": "Delete a repository record, or ensure it doesn't exist. Requires auth, implemented by PDS.", "input": { "encoding": "application/json", "schema": { @@ -14,7 +14,7 @@ "repo": { "type": "string", "format": "at-identifier", - "description": "The handle or DID of the repo." + "description": "The handle or DID of the repo (aka, current account)." }, "collection": { "type": "string", @@ -23,7 +23,7 @@ }, "rkey": { "type": "string", - "description": "The key of the record." + "description": "The Record Key." }, "swapRecord": { "type": "string", diff --git a/lexicons/com/atproto/repo/describeRepo.json b/lexicons/com/atproto/repo/describeRepo.json index b7f283bff70..b1ce2b6cf9e 100644 --- a/lexicons/com/atproto/repo/describeRepo.json +++ b/lexicons/com/atproto/repo/describeRepo.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get information about the repo, including the list of collections.", + "description": "Get information about an account and repository, including the list of collections. Does not require auth.", "parameters": { "type": "params", "required": ["repo"], @@ -30,12 +30,19 @@ "properties": { "handle": { "type": "string", "format": "handle" }, "did": { "type": "string", "format": "did" }, - "didDoc": { "type": "unknown" }, + "didDoc": { + "type": "unknown", + "description": "The complete DID document for this account." + }, "collections": { "type": "array", + "description": "List of all the collections (NSIDs) for which this repo contains at least one record.", "items": { "type": "string", "format": "nsid" } }, - "handleIsCorrect": { "type": "boolean" } + "handleIsCorrect": { + "type": "boolean", + "description": "Indicates if handle is currently valid (resolves bi-directionally)" + } } } } diff --git a/lexicons/com/atproto/repo/getRecord.json b/lexicons/com/atproto/repo/getRecord.json index ec4d17e4260..5d8bb173470 100644 --- a/lexicons/com/atproto/repo/getRecord.json +++ b/lexicons/com/atproto/repo/getRecord.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get a record.", + "description": "Get a single record from a repository. Does not require auth.", "parameters": { "type": "params", "required": ["repo", "collection", "rkey"], @@ -19,7 +19,7 @@ "format": "nsid", "description": "The NSID of the record collection." }, - "rkey": { "type": "string", "description": "The key of the record." }, + "rkey": { "type": "string", "description": "The Record Key." }, "cid": { "type": "string", "format": "cid", diff --git a/lexicons/com/atproto/repo/listRecords.json b/lexicons/com/atproto/repo/listRecords.json index ac04e3e8782..bc91c952bb1 100644 --- a/lexicons/com/atproto/repo/listRecords.json +++ b/lexicons/com/atproto/repo/listRecords.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "List a range of records in a collection.", + "description": "List a range of records in a repository, matching a specific collection. Does not require auth.", "parameters": { "type": "params", "required": ["repo", "collection"], diff --git a/lexicons/com/atproto/repo/putRecord.json b/lexicons/com/atproto/repo/putRecord.json index ae39bd95ead..51f11c0f13f 100644 --- a/lexicons/com/atproto/repo/putRecord.json +++ b/lexicons/com/atproto/repo/putRecord.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Write a record, creating or updating it as needed.", + "description": "Write a repository record, creating or updating it as needed. Requires auth, implemented by PDS.", "input": { "encoding": "application/json", "schema": { @@ -15,7 +15,7 @@ "repo": { "type": "string", "format": "at-identifier", - "description": "The handle or DID of the repo." + "description": "The handle or DID of the repo (aka, current account)." }, "collection": { "type": "string", @@ -24,13 +24,13 @@ }, "rkey": { "type": "string", - "description": "The key of the record.", + "description": "The Record Key.", "maxLength": 15 }, "validate": { "type": "boolean", "default": true, - "description": "Flag for validating the record." + "description": "Can be set to 'false' to skip Lexicon schema validation of record data." }, "record": { "type": "unknown", @@ -39,7 +39,7 @@ "swapRecord": { "type": "string", "format": "cid", - "description": "Compare and swap with the previous record by CID." + "description": "Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation" }, "swapCommit": { "type": "string", diff --git a/lexicons/com/atproto/repo/uploadBlob.json b/lexicons/com/atproto/repo/uploadBlob.json index 63d1671bd3e..547a995a051 100644 --- a/lexicons/com/atproto/repo/uploadBlob.json +++ b/lexicons/com/atproto/repo/uploadBlob.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Upload a new blob to be added to repo in a later request.", + "description": "Upload a new blob, to be referenced from a repository record. The blob will be deleted if it is not referenced within a time window (eg, minutes). Blob restrictions (mimetype, size, etc) are enforced when the reference is created. Requires auth, implemented by PDS.", "input": { "encoding": "*/*" }, diff --git a/lexicons/com/atproto/server/createAccount.json b/lexicons/com/atproto/server/createAccount.json index d1456e095ae..b32bbe1569d 100644 --- a/lexicons/com/atproto/server/createAccount.json +++ b/lexicons/com/atproto/server/createAccount.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Create an account.", + "description": "Create an account. Implemented by PDS.", "input": { "encoding": "application/json", "schema": { @@ -12,14 +12,31 @@ "required": ["handle"], "properties": { "email": { "type": "string" }, - "handle": { "type": "string", "format": "handle" }, - "did": { "type": "string", "format": "did" }, + "handle": { + "type": "string", + "format": "handle", + "description": "Requested handle for the account." + }, + "did": { + "type": "string", + "format": "did", + "description": "Pre-existing atproto DID, being imported to a new account." + }, "inviteCode": { "type": "string" }, "verificationCode": { "type": "string" }, "verificationPhone": { "type": "string" }, - "password": { "type": "string" }, - "recoveryKey": { "type": "string" }, - "plcOp": { "type": "unknown" } + "password": { + "type": "string", + "description": "Initial account password. May need to meet instance-specific password strength requirements." + }, + "recoveryKey": { + "type": "string", + "description": "DID PLC rotation key (aka, recovery key) to be included in PLC creation operation." + }, + "plcOp": { + "type": "unknown", + "description": "A signed DID PLC operation to be submitted as part of importing an existing account to this instance. NOTE: this optional field may be updated when full account migration is implemented." + } } } }, @@ -27,13 +44,21 @@ "encoding": "application/json", "schema": { "type": "object", + "description": "Account login session returned on successful account creation.", "required": ["accessJwt", "refreshJwt", "handle", "did"], "properties": { "accessJwt": { "type": "string" }, "refreshJwt": { "type": "string" }, "handle": { "type": "string", "format": "handle" }, - "did": { "type": "string", "format": "did" }, - "didDoc": { "type": "unknown" } + "did": { + "type": "string", + "format": "did", + "description": "The DID of the new account." + }, + "didDoc": { + "type": "unknown", + "description": "Complete DID document." + } } } }, diff --git a/lexicons/com/atproto/server/createAppPassword.json b/lexicons/com/atproto/server/createAppPassword.json index f12e8e2557e..0a60e4e30b0 100644 --- a/lexicons/com/atproto/server/createAppPassword.json +++ b/lexicons/com/atproto/server/createAppPassword.json @@ -11,7 +11,10 @@ "type": "object", "required": ["name"], "properties": { - "name": { "type": "string" } + "name": { + "type": "string", + "description": "A short name for the App Password, to help distinguish them." + } } } }, diff --git a/lexicons/com/atproto/server/deleteAccount.json b/lexicons/com/atproto/server/deleteAccount.json index 3747189dca3..cf4babfe7da 100644 --- a/lexicons/com/atproto/server/deleteAccount.json +++ b/lexicons/com/atproto/server/deleteAccount.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Delete an actor's account with a token and password.", + "description": "Delete an actor's account with a token and password. Can only be called after requesting a deletion token. Requires auth.", "input": { "encoding": "application/json", "schema": { diff --git a/lexicons/com/atproto/server/deleteSession.json b/lexicons/com/atproto/server/deleteSession.json index e05d019024a..807a89dc9bd 100644 --- a/lexicons/com/atproto/server/deleteSession.json +++ b/lexicons/com/atproto/server/deleteSession.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Delete the current session." + "description": "Delete the current session. Requires auth." } } } diff --git a/lexicons/com/atproto/server/describeServer.json b/lexicons/com/atproto/server/describeServer.json index 3c60a58ecaf..908cb2127f9 100644 --- a/lexicons/com/atproto/server/describeServer.json +++ b/lexicons/com/atproto/server/describeServer.json @@ -4,20 +4,31 @@ "defs": { "main": { "type": "query", - "description": "Get a document describing the service's accounts configuration.", + "description": "Describes the server's account creation requirements and capabilities. Implemented by PDS.", "output": { "encoding": "application/json", "schema": { "type": "object", "required": ["availableUserDomains"], "properties": { - "inviteCodeRequired": { "type": "boolean" }, - "phoneVerificationRequired": { "type": "boolean" }, + "inviteCodeRequired": { + "type": "boolean", + "description": "If true, an invite code must be supplied to create an account on this instance." + }, + "phoneVerificationRequired": { + "type": "boolean", + "description": "If true, a phone verification token must be supplied to create an account on this instance." + }, "availableUserDomains": { "type": "array", + "description": "List of domain suffixes that can be used in account handles.", "items": { "type": "string" } }, - "links": { "type": "ref", "ref": "#links" } + "links": { + "type": "ref", + "description": "URLs of service policy documents.", + "ref": "#links" + } } } } diff --git a/lexicons/com/atproto/server/getAccountInviteCodes.json b/lexicons/com/atproto/server/getAccountInviteCodes.json index ac23b11f23f..72f0822703d 100644 --- a/lexicons/com/atproto/server/getAccountInviteCodes.json +++ b/lexicons/com/atproto/server/getAccountInviteCodes.json @@ -4,12 +4,16 @@ "defs": { "main": { "type": "query", - "description": "Get all invite codes for a given account.", + "description": "Get all invite codes for the current account. Requires auth.", "parameters": { "type": "params", "properties": { "includeUsed": { "type": "boolean", "default": true }, - "createAvailable": { "type": "boolean", "default": true } + "createAvailable": { + "type": "boolean", + "default": true, + "description": "Controls whether any new 'earned' but not 'created' invites should be created." + } } }, "output": { diff --git a/lexicons/com/atproto/server/getSession.json b/lexicons/com/atproto/server/getSession.json index 5f7700882da..6b5f280e746 100644 --- a/lexicons/com/atproto/server/getSession.json +++ b/lexicons/com/atproto/server/getSession.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get information about the current session.", + "description": "Get information about the current auth session. Requires auth.", "output": { "encoding": "application/json", "schema": { diff --git a/lexicons/com/atproto/server/refreshSession.json b/lexicons/com/atproto/server/refreshSession.json index 3f4d7fdf272..0b067f86b7f 100644 --- a/lexicons/com/atproto/server/refreshSession.json +++ b/lexicons/com/atproto/server/refreshSession.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Refresh an authentication session.", + "description": "Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt').", "output": { "encoding": "application/json", "schema": { diff --git a/lexicons/com/atproto/server/reserveSigningKey.json b/lexicons/com/atproto/server/reserveSigningKey.json index 3a67ad0a3c8..a33e1ede68e 100644 --- a/lexicons/com/atproto/server/reserveSigningKey.json +++ b/lexicons/com/atproto/server/reserveSigningKey.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Reserve a repo signing key for account creation.", + "description": "Reserve a repo signing key, for use with account creation. Necessary so that a DID PLC update operation can be constructed during an account migraiton. Public and does not require auth; implemented by PDS. NOTE: this endpoint may change when full account migration is implemented.", "input": { "encoding": "application/json", "schema": { @@ -12,7 +12,8 @@ "properties": { "did": { "type": "string", - "description": "The did to reserve a new did:key for" + "format": "did", + "description": "The DID to reserve a key for." } } } @@ -25,7 +26,7 @@ "properties": { "signingKey": { "type": "string", - "description": "Public signing key in the form of a did:key." + "description": "The public key for the reserved signing key, in did:key serialization." } } } diff --git a/lexicons/com/atproto/sync/getBlob.json b/lexicons/com/atproto/sync/getBlob.json index 23e18a4f3b5..57ece7a9d8a 100644 --- a/lexicons/com/atproto/sync/getBlob.json +++ b/lexicons/com/atproto/sync/getBlob.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get a blob associated with a given repo.", + "description": "Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS.", "parameters": { "type": "params", "required": ["did", "cid"], @@ -12,7 +12,7 @@ "did": { "type": "string", "format": "did", - "description": "The DID of the repo." + "description": "The DID of the account." }, "cid": { "type": "string", diff --git a/lexicons/com/atproto/sync/getBlocks.json b/lexicons/com/atproto/sync/getBlocks.json index cf776a0c88f..29dd4971904 100644 --- a/lexicons/com/atproto/sync/getBlocks.json +++ b/lexicons/com/atproto/sync/getBlocks.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get blocks from a given repo.", + "description": "Get data blocks from a given repo, by CID. For example, intermediate MST nodes, or records. Does not require auth; implemented by PDS.", "parameters": { "type": "params", "required": ["did", "cids"], diff --git a/lexicons/com/atproto/sync/getLatestCommit.json b/lexicons/com/atproto/sync/getLatestCommit.json index d8754f09062..ac7faf57570 100644 --- a/lexicons/com/atproto/sync/getLatestCommit.json +++ b/lexicons/com/atproto/sync/getLatestCommit.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get the current commit CID & revision of the repo.", + "description": "Get the current commit CID & revision of the specified repo. Does not require auth.", "parameters": { "type": "params", "required": ["did"], diff --git a/lexicons/com/atproto/sync/getRecord.json b/lexicons/com/atproto/sync/getRecord.json index cbd0ad3a5ac..718245a5195 100644 --- a/lexicons/com/atproto/sync/getRecord.json +++ b/lexicons/com/atproto/sync/getRecord.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Get blocks needed for existence or non-existence of record.", + "description": "Get data blocks needed to prove the existence or non-existence of record in the current version of repo. Does not require auth.", "parameters": { "type": "params", "required": ["did", "collection", "rkey"], @@ -15,7 +15,7 @@ "description": "The DID of the repo." }, "collection": { "type": "string", "format": "nsid" }, - "rkey": { "type": "string" }, + "rkey": { "type": "string", "description": "Record Key" }, "commit": { "type": "string", "format": "cid", diff --git a/lexicons/com/atproto/sync/getRepo.json b/lexicons/com/atproto/sync/getRepo.json index fb68ab670ee..7fa710abfb5 100644 --- a/lexicons/com/atproto/sync/getRepo.json +++ b/lexicons/com/atproto/sync/getRepo.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Gets the DID's repo, optionally catching up from a specific revision.", + "description": "Download a repository export as CAR file. Optionally only a 'diff' since a previous revision. Does not require auth; implemented by PDS.", "parameters": { "type": "params", "required": ["did"], @@ -16,7 +16,7 @@ }, "since": { "type": "string", - "description": "The revision of the repo to catch up from." + "description": "The revision ('rev') of the repo to create a diff from." } } }, diff --git a/lexicons/com/atproto/sync/listBlobs.json b/lexicons/com/atproto/sync/listBlobs.json index 46815eeb49a..b4c954d999a 100644 --- a/lexicons/com/atproto/sync/listBlobs.json +++ b/lexicons/com/atproto/sync/listBlobs.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "List blob CIDs since some revision.", + "description": "List blob CIDso for an account, since some repo revision. Does not require auth; implemented by PDS.", "parameters": { "type": "params", "required": ["did"], diff --git a/lexicons/com/atproto/sync/listRepos.json b/lexicons/com/atproto/sync/listRepos.json index 440e8693d5e..07ae35e2c5e 100644 --- a/lexicons/com/atproto/sync/listRepos.json +++ b/lexicons/com/atproto/sync/listRepos.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "List DIDs and root CIDs of hosted repos.", + "description": "Enumerates all the DID, rev, and commit CID for all repos hosted by this service. Does not require auth; implemented by PDS and Relay.", "parameters": { "type": "params", "properties": { @@ -37,7 +37,11 @@ "required": ["did", "head", "rev"], "properties": { "did": { "type": "string", "format": "did" }, - "head": { "type": "string", "format": "cid" }, + "head": { + "type": "string", + "format": "cid", + "description": "Current repo commit CID" + }, "rev": { "type": "string" } } } diff --git a/lexicons/com/atproto/sync/notifyOfUpdate.json b/lexicons/com/atproto/sync/notifyOfUpdate.json index 48cb4b24678..034a9655a08 100644 --- a/lexicons/com/atproto/sync/notifyOfUpdate.json +++ b/lexicons/com/atproto/sync/notifyOfUpdate.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Notify a crawling service of a recent update; often when a long break between updates causes the connection with the crawling service to break.", + "description": "Notify a crawling service of a recent update, and that crawling should resume. Intended use is after a gap between repo stream events caused the crawling service to disconnect. Does not require auth; implemented by Relay.", "input": { "encoding": "application/json", "schema": { @@ -13,7 +13,7 @@ "properties": { "hostname": { "type": "string", - "description": "Hostname of the service that is notifying of update." + "description": "Hostname of the current service (usually a PDS) that is notifying of update." } } } diff --git a/lexicons/com/atproto/sync/requestCrawl.json b/lexicons/com/atproto/sync/requestCrawl.json index a3520a33180..8e075a376fc 100644 --- a/lexicons/com/atproto/sync/requestCrawl.json +++ b/lexicons/com/atproto/sync/requestCrawl.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Request a service to persistently crawl hosted repos.", + "description": "Request a service to persistently crawl hosted repos. Expected use is new PDS instances declaring their existence to Relays. Does not require auth.", "input": { "encoding": "application/json", "schema": { @@ -13,7 +13,7 @@ "properties": { "hostname": { "type": "string", - "description": "Hostname of the service that is requesting to be crawled." + "description": "Hostname of the current service (eg, PDS) that is requesting to be crawled." } } } diff --git a/lexicons/com/atproto/sync/subscribeRepos.json b/lexicons/com/atproto/sync/subscribeRepos.json index 9a5c0f6153c..73a34a3b49e 100644 --- a/lexicons/com/atproto/sync/subscribeRepos.json +++ b/lexicons/com/atproto/sync/subscribeRepos.json @@ -4,13 +4,13 @@ "defs": { "main": { "type": "subscription", - "description": "Subscribe to repo updates.", + "description": "Repository event stream, aka Firehose endpoint. Outputs repo commits with diff data, and identity update events, for all repositories on the current server. See the atproto specifications for details around stream sequencing, repo versioning, CAR diff format, and more. Public and does not require auth; implemented by PDS and Relay.", "parameters": { "type": "params", "properties": { "cursor": { "type": "integer", - "description": "The last known event to backfill from." + "description": "The last known event seq number to backfill from." } } }, @@ -20,10 +20,17 @@ "refs": ["#commit", "#handle", "#migrate", "#tombstone", "#info"] } }, - "errors": [{ "name": "FutureCursor" }, { "name": "ConsumerTooSlow" }] + "errors": [ + { "name": "FutureCursor" }, + { + "name": "ConsumerTooSlow", + "description": "If the consumer of the stream can not keep up with events, and a backlog gets too large, the server will drop the connection." + } + ] }, "commit": { "type": "object", + "description": "Represents an update of repository state. Note that empty commits are allowed, which include no repo data changes, but an update to rev and signature.", "required": [ "seq", "rebase", @@ -39,39 +46,67 @@ ], "nullable": ["prev", "since"], "properties": { - "seq": { "type": "integer" }, - "rebase": { "type": "boolean" }, - "tooBig": { "type": "boolean" }, - "repo": { "type": "string", "format": "did" }, - "commit": { "type": "cid-link" }, - "prev": { "type": "cid-link" }, + "seq": { + "type": "integer", + "description": "The stream sequence number of this message." + }, + "rebase": { "type": "boolean", "description": "DEPRECATED -- unused" }, + "tooBig": { + "type": "boolean", + "description": "Indicates that this commit contained too many ops, or data size was too large. Consumers will need to make a separate request to get missing data." + }, + "repo": { + "type": "string", + "format": "did", + "description": "The repo this event comes from." + }, + "commit": { + "type": "cid-link", + "description": "Repo commit object CID." + }, + "prev": { + "type": "cid-link", + "description": "DEPRECATED -- unused. WARNING -- nullable and optional; stick with optional to ensure golang interoperability." + }, "rev": { "type": "string", - "description": "The rev of the emitted commit." + "description": "The rev of the emitted commit. Note that this information is also in the commit object included in blocks, unless this is a tooBig event." }, "since": { "type": "string", - "description": "The rev of the last emitted commit from this repo." + "description": "The rev of the last emitted commit from this repo (if any)." }, "blocks": { "type": "bytes", - "description": "CAR file containing relevant blocks.", + "description": "CAR file containing relevant blocks, as a diff since the previous repo state.", "maxLength": 1000000 }, "ops": { "type": "array", - "items": { "type": "ref", "ref": "#repoOp" }, + "items": { + "type": "ref", + "ref": "#repoOp", + "description": "List of repo mutation operations in this commit (eg, records created, updated, or deleted)." + }, "maxLength": 200 }, "blobs": { "type": "array", - "items": { "type": "cid-link" } + "items": { + "type": "cid-link", + "description": "List of new blobs (by CID) referenced by records in this commit." + } }, - "time": { "type": "string", "format": "datetime" } + "time": { + "type": "string", + "format": "datetime", + "description": "Timestamp of when this message was originally broadcast." + } } }, "handle": { "type": "object", + "description": "Represents an update of the account's handle, or transition to/from invalid state.", "required": ["seq", "did", "handle", "time"], "properties": { "seq": { "type": "integer" }, @@ -82,6 +117,7 @@ }, "migrate": { "type": "object", + "description": "Represents an account moving from one PDS instance to another. NOTE: not implemented; full account migration may introduce a new message instead.", "required": ["seq", "did", "migrateTo", "time"], "nullable": ["migrateTo"], "properties": { @@ -93,6 +129,7 @@ }, "tombstone": { "type": "object", + "description": "Indicates that an account has been deleted.", "required": ["seq", "did", "time"], "properties": { "seq": { "type": "integer" }, @@ -115,7 +152,7 @@ }, "repoOp": { "type": "object", - "description": "A repo operation, ie a write of a single record. For creates and updates, CID is the record's CID as of this operation. For deletes, it's null.", + "description": "A repo operation, ie a mutation of a single record.", "required": ["action", "path", "cid"], "nullable": ["cid"], "properties": { @@ -124,7 +161,10 @@ "knownValues": ["create", "update", "delete"] }, "path": { "type": "string" }, - "cid": { "type": "cid-link" } + "cid": { + "type": "cid-link", + "description": "For creates and updates, the new record CID. For deletions, null." + } } } } diff --git a/lexicons/com/atproto/temp/fetchLabels.json b/lexicons/com/atproto/temp/fetchLabels.json index 14e392fd5e7..d76041ac296 100644 --- a/lexicons/com/atproto/temp/fetchLabels.json +++ b/lexicons/com/atproto/temp/fetchLabels.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "query", - "description": "Fetch all labels from a labeler created after a certain date.", + "description": "Fetch all labels from a labeler created after a certain date. DEPRECATED: use queryLabels or subscribeLabels instead", "parameters": { "type": "params", "properties": { diff --git a/lexicons/com/atproto/temp/transferAccount.json b/lexicons/com/atproto/temp/transferAccount.json index 3cb2035ac0e..d4687d9b6e1 100644 --- a/lexicons/com/atproto/temp/transferAccount.json +++ b/lexicons/com/atproto/temp/transferAccount.json @@ -4,7 +4,7 @@ "defs": { "main": { "type": "procedure", - "description": "Transfer an account.", + "description": "Transfer an account. NOTE: temporary method, necessarily how account migration will be implemented.", "input": { "encoding": "application/json", "schema": { diff --git a/packages/api/src/client/lexicons.ts b/packages/api/src/client/lexicons.ts index 9db3be4f817..f3490b79dfd 100644 --- a/packages/api/src/client/lexicons.ts +++ b/packages/api/src/client/lexicons.ts @@ -303,6 +303,12 @@ export const schemaDict = { type: 'string', format: 'datetime', }, + tags: { + type: 'array', + items: { + type: 'string', + }, + }, }, }, reportViewDetail: { @@ -897,6 +903,33 @@ export const schemaDict = { }, }, }, + modEventTag: { + type: 'object', + description: 'Add/Remove a tag on a subject', + required: ['add', 'remove'], + properties: { + add: { + type: 'array', + items: { + type: 'string', + }, + description: + "Tags to be added to the subject. If already exists, won't be duplicated.", + }, + remove: { + type: 'array', + items: { + type: 'string', + }, + description: + "Tags to be removed to the subject. Ignores a tag If it doesn't exist, won't be duplicated.", + }, + comment: { + type: 'string', + description: 'Additional comment about added/removed tags.', + }, + }, + }, communicationTemplateView: { type: 'object', required: [ @@ -1075,6 +1108,7 @@ export const schemaDict = { 'lex:com.atproto.admin.defs#modEventReverseTakedown', 'lex:com.atproto.admin.defs#modEventUnmute', 'lex:com.atproto.admin.defs#modEventEmail', + 'lex:com.atproto.admin.defs#modEventTag', ], }, subject: { @@ -1503,6 +1537,22 @@ export const schemaDict = { description: 'If specified, only events where all of these labels were removed are returned', }, + addedTags: { + type: 'array', + items: { + type: 'string', + }, + description: + 'If specified, only events where all of these tags were added are returned', + }, + removedTags: { + type: 'array', + items: { + type: 'string', + }, + description: + 'If specified, only events where all of these tags were removed are returned', + }, reportTypes: { type: 'array', items: { @@ -1620,6 +1670,18 @@ export const schemaDict = { maximum: 100, default: 50, }, + tags: { + type: 'array', + items: { + type: 'string', + }, + }, + excludeTags: { + type: 'array', + items: { + type: 'string', + }, + }, cursor: { type: 'string', }, @@ -1912,7 +1974,7 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Provides the DID of a repo.', + description: 'Resolves a handle (domain name) to a DID.', parameters: { type: 'params', required: ['handle'], @@ -1946,7 +2008,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Updates the handle of the account.', + description: + "Updates the current account's handle. Verifies handle validity, and updates did:plc document if necessary. Implemented by PDS, and requires auth.", input: { encoding: 'application/json', schema: { @@ -1956,6 +2019,7 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'The new handle.', }, }, }, @@ -2046,7 +2110,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Find labels relevant to the provided URI patterns.', + description: + 'Find labels relevant to the provided AT-URI patterns. Public endpoint for moderation services, though may return different or additional results with auth.', parameters: { type: 'params', required: ['uriPatterns'], @@ -2107,13 +2172,14 @@ export const schemaDict = { defs: { main: { type: 'subscription', - description: 'Subscribe to label updates.', + description: + 'Subscribe to stream of labels (and negations). Public endpoint implemented by mod services. Uses same sequencing scheme as repo event stream.', parameters: { type: 'params', properties: { cursor: { type: 'integer', - description: 'The last known event to backfill from.', + description: 'The last known event seq number to backfill from.', }, }, }, @@ -2169,7 +2235,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Report a repo or a record.', + description: + 'Submit a moderation report regarding an atproto account or record. Implemented by moderation services (with PDS proxying), and requires auth.', input: { encoding: 'application/json', schema: { @@ -2178,10 +2245,14 @@ export const schemaDict = { properties: { reasonType: { type: 'ref', + description: + 'Indicates the broad category of violation the report is for.', ref: 'lex:com.atproto.moderation.defs#reasonType', }, reason: { type: 'string', + description: + 'Additional context about the content and violation.', }, subject: { type: 'union', @@ -2292,7 +2363,7 @@ export const schemaDict = { main: { type: 'procedure', description: - 'Apply a batch transaction of creates, updates, and deletes.', + 'Apply a batch transaction of repository creates, updates, and deletes. Requires auth, implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2302,12 +2373,14 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, validate: { type: 'boolean', default: true, - description: 'Flag for validating the records.', + description: + "Can be set to 'false' to skip Lexicon schema validation of record data, for all operations.", }, writes: { type: 'array', @@ -2323,6 +2396,8 @@ export const schemaDict = { }, swapCommit: { type: 'string', + description: + 'If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations.', format: 'cid', }, }, @@ -2331,12 +2406,14 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that the 'swapCommit' parameter did not match current commit.", }, ], }, create: { type: 'object', - description: 'Create a new record.', + description: 'Operation which creates a new record.', required: ['collection', 'value'], properties: { collection: { @@ -2354,7 +2431,7 @@ export const schemaDict = { }, update: { type: 'object', - description: 'Update an existing record.', + description: 'Operation which updates an existing record.', required: ['collection', 'rkey', 'value'], properties: { collection: { @@ -2371,7 +2448,7 @@ export const schemaDict = { }, delete: { type: 'object', - description: 'Delete an existing record.', + description: 'Operation which deletes an existing record.', required: ['collection', 'rkey'], properties: { collection: { @@ -2391,7 +2468,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Create a new record.', + description: + 'Create a single new repository record. Requires auth, implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2401,7 +2479,8 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, collection: { type: 'string', @@ -2410,17 +2489,18 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', maxLength: 15, }, validate: { type: 'boolean', default: true, - description: 'Flag for validating the record.', + description: + "Can be set to 'false' to skip Lexicon schema validation of record data.", }, record: { type: 'unknown', - description: 'The record to create.', + description: 'The record itself. Must contain a $type field.', }, swapCommit: { type: 'string', @@ -2451,6 +2531,8 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that 'swapCommit' didn't match current repo commit.", }, ], }, @@ -2462,7 +2544,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: "Delete a record, or ensure it doesn't exist.", + description: + "Delete a repository record, or ensure it doesn't exist. Requires auth, implemented by PDS.", input: { encoding: 'application/json', schema: { @@ -2472,7 +2555,8 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, collection: { type: 'string', @@ -2481,7 +2565,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, swapRecord: { type: 'string', @@ -2513,7 +2597,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Get information about the repo, including the list of collections.', + 'Get information about an account and repository, including the list of collections. Does not require auth.', parameters: { type: 'params', required: ['repo'], @@ -2547,9 +2631,12 @@ export const schemaDict = { }, didDoc: { type: 'unknown', + description: 'The complete DID document for this account.', }, collections: { type: 'array', + description: + 'List of all the collections (NSIDs) for which this repo contains at least one record.', items: { type: 'string', format: 'nsid', @@ -2557,6 +2644,8 @@ export const schemaDict = { }, handleIsCorrect: { type: 'boolean', + description: + 'Indicates if handle is currently valid (resolves bi-directionally)', }, }, }, @@ -2570,7 +2659,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a record.', + description: + 'Get a single record from a repository. Does not require auth.', parameters: { type: 'params', required: ['repo', 'collection', 'rkey'], @@ -2587,7 +2677,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, cid: { type: 'string', @@ -2626,7 +2716,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'List a range of records in a collection.', + description: + 'List a range of records in a repository, matching a specific collection. Does not require auth.', parameters: { type: 'params', required: ['repo', 'collection'], @@ -2712,7 +2803,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Write a record, creating or updating it as needed.', + description: + 'Write a repository record, creating or updating it as needed. Requires auth, implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2723,7 +2815,8 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, collection: { type: 'string', @@ -2732,13 +2825,14 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', maxLength: 15, }, validate: { type: 'boolean', default: true, - description: 'Flag for validating the record.', + description: + "Can be set to 'false' to skip Lexicon schema validation of record data.", }, record: { type: 'unknown', @@ -2748,7 +2842,7 @@ export const schemaDict = { type: 'string', format: 'cid', description: - 'Compare and swap with the previous record by CID.', + 'Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation', }, swapCommit: { type: 'string', @@ -2812,7 +2906,7 @@ export const schemaDict = { main: { type: 'procedure', description: - 'Upload a new blob to be added to repo in a later request.', + 'Upload a new blob, to be referenced from a repository record. The blob will be deleted if it is not referenced within a time window (eg, minutes). Blob restrictions (mimetype, size, etc) are enforced when the reference is created. Requires auth, implemented by PDS.', input: { encoding: '*/*', }, @@ -2877,7 +2971,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Create an account.', + description: 'Create an account. Implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2890,10 +2984,13 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'Requested handle for the account.', }, did: { type: 'string', format: 'did', + description: + 'Pre-existing atproto DID, being imported to a new account.', }, inviteCode: { type: 'string', @@ -2906,12 +3003,18 @@ export const schemaDict = { }, password: { type: 'string', + description: + 'Initial account password. May need to meet instance-specific password strength requirements.', }, recoveryKey: { type: 'string', + description: + 'DID PLC rotation key (aka, recovery key) to be included in PLC creation operation.', }, plcOp: { type: 'unknown', + description: + 'A signed DID PLC operation to be submitted as part of importing an existing account to this instance. NOTE: this optional field may be updated when full account migration is implemented.', }, }, }, @@ -2920,6 +3023,8 @@ export const schemaDict = { encoding: 'application/json', schema: { type: 'object', + description: + 'Account login session returned on successful account creation.', required: ['accessJwt', 'refreshJwt', 'handle', 'did'], properties: { accessJwt: { @@ -2935,9 +3040,11 @@ export const schemaDict = { did: { type: 'string', format: 'did', + description: 'The DID of the new account.', }, didDoc: { type: 'unknown', + description: 'Complete DID document.', }, }, }, @@ -2983,6 +3090,8 @@ export const schemaDict = { properties: { name: { type: 'string', + description: + 'A short name for the App Password, to help distinguish them.', }, }, }, @@ -3250,7 +3359,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: "Delete an actor's account with a token and password.", + description: + "Delete an actor's account with a token and password. Can only be called after requesting a deletion token. Requires auth.", input: { encoding: 'application/json', schema: { @@ -3287,7 +3397,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Delete the current session.', + description: 'Delete the current session. Requires auth.', }, }, }, @@ -3298,7 +3408,7 @@ export const schemaDict = { main: { type: 'query', description: - "Get a document describing the service's accounts configuration.", + "Describes the server's account creation requirements and capabilities. Implemented by PDS.", output: { encoding: 'application/json', schema: { @@ -3307,18 +3417,25 @@ export const schemaDict = { properties: { inviteCodeRequired: { type: 'boolean', + description: + 'If true, an invite code must be supplied to create an account on this instance.', }, phoneVerificationRequired: { type: 'boolean', + description: + 'If true, a phone verification token must be supplied to create an account on this instance.', }, availableUserDomains: { type: 'array', + description: + 'List of domain suffixes that can be used in account handles.', items: { type: 'string', }, }, links: { type: 'ref', + description: 'URLs of service policy documents.', ref: 'lex:com.atproto.server.describeServer#links', }, }, @@ -3344,7 +3461,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get all invite codes for a given account.', + description: + 'Get all invite codes for the current account. Requires auth.', parameters: { type: 'params', properties: { @@ -3355,6 +3473,8 @@ export const schemaDict = { createAvailable: { type: 'boolean', default: true, + description: + "Controls whether any new 'earned' but not 'created' invites should be created.", }, }, }, @@ -3388,7 +3508,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get information about the current session.', + description: + 'Get information about the current auth session. Requires auth.', output: { encoding: 'application/json', schema: { @@ -3468,7 +3589,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Refresh an authentication session.', + description: + "Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt').", output: { encoding: 'application/json', schema: { @@ -3574,7 +3696,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Reserve a repo signing key for account creation.', + description: + 'Reserve a repo signing key, for use with account creation. Necessary so that a DID PLC update operation can be constructed during an account migraiton. Public and does not require auth; implemented by PDS. NOTE: this endpoint may change when full account migration is implemented.', input: { encoding: 'application/json', schema: { @@ -3582,7 +3705,8 @@ export const schemaDict = { properties: { did: { type: 'string', - description: 'The did to reserve a new did:key for', + format: 'did', + description: 'The DID to reserve a key for.', }, }, }, @@ -3595,7 +3719,8 @@ export const schemaDict = { properties: { signingKey: { type: 'string', - description: 'Public signing key in the form of a did:key.', + description: + 'The public key for the reserved signing key, in did:key serialization.', }, }, }, @@ -3702,7 +3827,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a blob associated with a given repo.', + description: + 'Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS.', parameters: { type: 'params', required: ['did', 'cid'], @@ -3710,7 +3836,7 @@ export const schemaDict = { did: { type: 'string', format: 'did', - description: 'The DID of the repo.', + description: 'The DID of the account.', }, cid: { type: 'string', @@ -3731,7 +3857,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get blocks from a given repo.', + description: + 'Get data blocks from a given repo, by CID. For example, intermediate MST nodes, or records. Does not require auth; implemented by PDS.', parameters: { type: 'params', required: ['did', 'cids'], @@ -3826,7 +3953,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get the current commit CID & revision of the repo.', + description: + 'Get the current commit CID & revision of the specified repo. Does not require auth.', parameters: { type: 'params', required: ['did'], @@ -3869,7 +3997,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Get blocks needed for existence or non-existence of record.', + 'Get data blocks needed to prove the existence or non-existence of record in the current version of repo. Does not require auth.', parameters: { type: 'params', required: ['did', 'collection', 'rkey'], @@ -3885,6 +4013,7 @@ export const schemaDict = { }, rkey: { type: 'string', + description: 'Record Key', }, commit: { type: 'string', @@ -3906,7 +4035,7 @@ export const schemaDict = { main: { type: 'query', description: - "Gets the DID's repo, optionally catching up from a specific revision.", + "Download a repository export as CAR file. Optionally only a 'diff' since a previous revision. Does not require auth; implemented by PDS.", parameters: { type: 'params', required: ['did'], @@ -3918,7 +4047,8 @@ export const schemaDict = { }, since: { type: 'string', - description: 'The revision of the repo to catch up from.', + description: + "The revision ('rev') of the repo to create a diff from.", }, }, }, @@ -3934,7 +4064,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'List blob CIDs since some revision.', + description: + 'List blob CIDso for an account, since some repo revision. Does not require auth; implemented by PDS.', parameters: { type: 'params', required: ['did'], @@ -3987,7 +4118,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'List DIDs and root CIDs of hosted repos.', + description: + 'Enumerates all the DID, rev, and commit CID for all repos hosted by this service. Does not require auth; implemented by PDS and Relay.', parameters: { type: 'params', properties: { @@ -4033,6 +4165,7 @@ export const schemaDict = { head: { type: 'string', format: 'cid', + description: 'Current repo commit CID', }, rev: { type: 'string', @@ -4048,7 +4181,7 @@ export const schemaDict = { main: { type: 'procedure', description: - 'Notify a crawling service of a recent update; often when a long break between updates causes the connection with the crawling service to break.', + 'Notify a crawling service of a recent update, and that crawling should resume. Intended use is after a gap between repo stream events caused the crawling service to disconnect. Does not require auth; implemented by Relay.', input: { encoding: 'application/json', schema: { @@ -4058,7 +4191,7 @@ export const schemaDict = { hostname: { type: 'string', description: - 'Hostname of the service that is notifying of update.', + 'Hostname of the current service (usually a PDS) that is notifying of update.', }, }, }, @@ -4072,7 +4205,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Request a service to persistently crawl hosted repos.', + description: + 'Request a service to persistently crawl hosted repos. Expected use is new PDS instances declaring their existence to Relays. Does not require auth.', input: { encoding: 'application/json', schema: { @@ -4082,7 +4216,7 @@ export const schemaDict = { hostname: { type: 'string', description: - 'Hostname of the service that is requesting to be crawled.', + 'Hostname of the current service (eg, PDS) that is requesting to be crawled.', }, }, }, @@ -4096,13 +4230,14 @@ export const schemaDict = { defs: { main: { type: 'subscription', - description: 'Subscribe to repo updates.', + description: + 'Repository event stream, aka Firehose endpoint. Outputs repo commits with diff data, and identity update events, for all repositories on the current server. See the atproto specifications for details around stream sequencing, repo versioning, CAR diff format, and more. Public and does not require auth; implemented by PDS and Relay.', parameters: { type: 'params', properties: { cursor: { type: 'integer', - description: 'The last known event to backfill from.', + description: 'The last known event seq number to backfill from.', }, }, }, @@ -4124,11 +4259,15 @@ export const schemaDict = { }, { name: 'ConsumerTooSlow', + description: + 'If the consumer of the stream can not keep up with events, and a backlog gets too large, the server will drop the connection.', }, ], }, commit: { type: 'object', + description: + 'Represents an update of repository state. Note that empty commits are allowed, which include no repo data changes, but an update to rev and signature.', required: [ 'seq', 'rebase', @@ -4146,34 +4285,45 @@ export const schemaDict = { properties: { seq: { type: 'integer', + description: 'The stream sequence number of this message.', }, rebase: { type: 'boolean', + description: 'DEPRECATED -- unused', }, tooBig: { type: 'boolean', + description: + 'Indicates that this commit contained too many ops, or data size was too large. Consumers will need to make a separate request to get missing data.', }, repo: { type: 'string', format: 'did', + description: 'The repo this event comes from.', }, commit: { type: 'cid-link', + description: 'Repo commit object CID.', }, prev: { type: 'cid-link', + description: + 'DEPRECATED -- unused. WARNING -- nullable and optional; stick with optional to ensure golang interoperability.', }, rev: { type: 'string', - description: 'The rev of the emitted commit.', + description: + 'The rev of the emitted commit. Note that this information is also in the commit object included in blocks, unless this is a tooBig event.', }, since: { type: 'string', - description: 'The rev of the last emitted commit from this repo.', + description: + 'The rev of the last emitted commit from this repo (if any).', }, blocks: { type: 'bytes', - description: 'CAR file containing relevant blocks.', + description: + 'CAR file containing relevant blocks, as a diff since the previous repo state.', maxLength: 1000000, }, ops: { @@ -4181,6 +4331,8 @@ export const schemaDict = { items: { type: 'ref', ref: 'lex:com.atproto.sync.subscribeRepos#repoOp', + description: + 'List of repo mutation operations in this commit (eg, records created, updated, or deleted).', }, maxLength: 200, }, @@ -4188,16 +4340,22 @@ export const schemaDict = { type: 'array', items: { type: 'cid-link', + description: + 'List of new blobs (by CID) referenced by records in this commit.', }, }, time: { type: 'string', format: 'datetime', + description: + 'Timestamp of when this message was originally broadcast.', }, }, }, handle: { type: 'object', + description: + "Represents an update of the account's handle, or transition to/from invalid state.", required: ['seq', 'did', 'handle', 'time'], properties: { seq: { @@ -4219,6 +4377,8 @@ export const schemaDict = { }, migrate: { type: 'object', + description: + 'Represents an account moving from one PDS instance to another. NOTE: not implemented; full account migration may introduce a new message instead.', required: ['seq', 'did', 'migrateTo', 'time'], nullable: ['migrateTo'], properties: { @@ -4240,6 +4400,7 @@ export const schemaDict = { }, tombstone: { type: 'object', + description: 'Indicates that an account has been deleted.', required: ['seq', 'did', 'time'], properties: { seq: { @@ -4270,8 +4431,7 @@ export const schemaDict = { }, repoOp: { type: 'object', - description: - "A repo operation, ie a write of a single record. For creates and updates, CID is the record's CID as of this operation. For deletes, it's null.", + description: 'A repo operation, ie a mutation of a single record.', required: ['action', 'path', 'cid'], nullable: ['cid'], properties: { @@ -4284,6 +4444,8 @@ export const schemaDict = { }, cid: { type: 'cid-link', + description: + 'For creates and updates, the new record CID. For deletions, null.', }, }, }, @@ -4324,7 +4486,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Fetch all labels from a labeler created after a certain date.', + 'Fetch all labels from a labeler created after a certain date. DEPRECATED: use queryLabels or subscribeLabels instead', parameters: { type: 'params', properties: { @@ -4440,7 +4602,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Transfer an account.', + description: + 'Transfer an account. NOTE: temporary method, necessarily how account migration will be implemented.', input: { encoding: 'application/json', schema: { @@ -4513,7 +4676,6 @@ export const schemaDict = { AppBskyActorDefs: { lexicon: 1, id: 'app.bsky.actor.defs', - description: 'A reference to an actor in the network.', defs: { profileViewBasic: { type: 'object', @@ -4646,6 +4808,8 @@ export const schemaDict = { }, 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', @@ -4731,6 +4895,9 @@ export const schemaDict = { format: 'at-uri', }, }, + timelineIndex: { + type: 'integer', + }, }, }, personalDetailsPref: { @@ -4815,7 +4982,8 @@ export const schemaDict = { 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: {}, @@ -4842,7 +5010,8 @@ export const schemaDict = { 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'], @@ -4850,6 +5019,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Handle or DID of account to fetch profile of.', }, }, }, @@ -4909,7 +5079,8 @@ export const schemaDict = { 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: { @@ -4952,7 +5123,7 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a profile.', + description: 'A declaration of a Bluesky account profile.', key: 'literal:self', record: { type: 'object', @@ -4964,21 +5135,28 @@ export const schemaDict = { }, 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: ['lex:com.atproto.label.defs#selfLabels'], }, }, @@ -5015,7 +5193,8 @@ export const schemaDict = { 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: { @@ -5067,7 +5246,8 @@ export const schemaDict = { 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: { @@ -5109,11 +5289,11 @@ export const schemaDict = { AppBskyEmbedExternal: { 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: { @@ -5177,7 +5357,7 @@ export const schemaDict = { AppBskyEmbedImages: { 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', @@ -5204,6 +5384,8 @@ export const schemaDict = { }, alt: { type: 'string', + description: + 'Alt text description of the image, for accessibility.', }, aspectRatio: { type: 'ref', @@ -5247,12 +5429,18 @@ export const schemaDict = { properties: { 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', @@ -5266,7 +5454,7 @@ export const schemaDict = { lexicon: 1, id: 'app.bsky.embed.record', description: - 'A representation of a record embedded in another form of content.', + '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', @@ -5312,6 +5500,7 @@ export const schemaDict = { }, value: { type: 'unknown', + description: 'The record data itself.', }, labels: { type: 'array', @@ -5376,7 +5565,7 @@ export const schemaDict = { lexicon: 1, id: 'app.bsky.embed.recordWithMedia', description: - 'A representation of a record embedded in another form of content, alongside other compatible embeds.', + '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', @@ -5475,6 +5664,8 @@ export const schemaDict = { }, 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', @@ -5735,7 +5926,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Get information about a feed generator, including policies and offered feed URIs.', + '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: { @@ -5790,7 +5981,8 @@ export const schemaDict = { 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', @@ -5824,6 +6016,7 @@ export const schemaDict = { }, labels: { type: 'union', + description: 'Self-label values', refs: ['lex:com.atproto.label.defs#selfLabels'], }, createdAt: { @@ -5841,7 +6034,8 @@ export const schemaDict = { 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'], @@ -5889,7 +6083,8 @@ export const schemaDict = { 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'], @@ -5945,7 +6140,8 @@ export const schemaDict = { 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'], @@ -5965,6 +6161,8 @@ export const schemaDict = { }, filter: { type: 'string', + description: + 'Combinations of post/repost types to include in response.', knownValues: [ 'posts_with_replies', 'posts_no_replies', @@ -6012,7 +6210,7 @@ export const schemaDict = { main: { type: 'query', description: - "Get a hydrated feed from an actor's selected feed generator.", + "Get a hydrated feed from an actor's selected feed generator. Implemented by App View.", parameters: { type: 'params', required: ['feed'], @@ -6065,7 +6263,8 @@ export const schemaDict = { 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'], @@ -6073,6 +6272,7 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: 'AT-URI of the feed generator record.', }, }, }, @@ -6088,9 +6288,13 @@ export const schemaDict = { }, 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.', }, }, }, @@ -6143,7 +6347,8 @@ export const schemaDict = { 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'], @@ -6151,6 +6356,8 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: + 'Reference to feed generator record describing the specific feed being requested.', }, limit: { type: 'integer', @@ -6196,7 +6403,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get the list of likes.', + description: + 'Get like records which reference a subject (by AT-URI and CID).', parameters: { type: 'params', required: ['uri'], @@ -6204,10 +6412,13 @@ export const schemaDict = { uri: { type: 'string', format: 'at-uri', + description: 'AT-URI of the subject (eg, a post record).', }, cid: { type: 'string', format: 'cid', + description: + 'CID of the subject record (aka, specific version of record), to filter likes.', }, limit: { type: 'integer', @@ -6274,7 +6485,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a view of a recent posts from actors in a list.', + description: + 'Get a feed of recent posts from a list (posts and reposts from any actors on the list). Does not require auth.', parameters: { type: 'params', required: ['list'], @@ -6282,6 +6494,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the list record.', }, limit: { type: 'integer', @@ -6327,7 +6540,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get posts in a thread.', + description: + 'Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.', parameters: { type: 'params', required: ['uri'], @@ -6335,15 +6549,20 @@ export const schemaDict = { uri: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to post record.', }, depth: { type: 'integer', + description: + 'How many levels of reply depth should be included in response.', default: 6, minimum: 0, maximum: 1000, }, parentHeight: { type: 'integer', + description: + 'How many levels of parent (and grandparent, etc) post to include.', default: 80, minimum: 0, maximum: 1000, @@ -6381,13 +6600,15 @@ export const schemaDict = { defs: { main: { type: 'query', - description: "Get a view of an actor's feed.", + description: + "Gets post views for a specified list of posts (by AT-URI). This is sometimes referred to as 'hydrating' a 'feed skeleton'.", parameters: { type: 'params', required: ['uris'], properties: { uris: { type: 'array', + description: 'List of post AT-URIs to return hydrated views for.', items: { type: 'string', format: 'at-uri', @@ -6421,7 +6642,7 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of reposts.', + description: 'Get a list of reposts for a given post.', parameters: { type: 'params', required: ['uri'], @@ -6429,10 +6650,13 @@ export const schemaDict = { uri: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) of post record', }, cid: { type: 'string', format: 'cid', + description: + 'If supplied, filters to reposts of specific version (by CID) of the post record.', }, limit: { type: 'integer', @@ -6481,7 +6705,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of suggested feeds for the viewer.', + description: + 'Get a list of suggested feeds (feed generators) for the requesting account.', parameters: { type: 'params', properties: { @@ -6524,12 +6749,15 @@ export const schemaDict = { defs: { main: { type: 'query', - description: "Get a view of the actor's home timeline.", + description: + "Get a view of the requesting account's home timeline. This is expected to be some form of reverse-chronological feed.", parameters: { type: 'params', properties: { algorithm: { type: 'string', + description: + "Variant 'algorithm' for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism.", }, limit: { type: 'integer', @@ -6570,7 +6798,7 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a like.', + description: "Record declaring a 'like' of a piece of subject content.", key: 'tid', record: { type: 'object', @@ -6595,7 +6823,7 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a post.', + description: 'Record containing a Bluesky post.', key: 'tid', record: { type: 'object', @@ -6605,10 +6833,12 @@ export const schemaDict = { type: 'string', maxLength: 3000, maxGraphemes: 300, + description: + 'The primary post content. May be an empty string, if there are embeds.', }, entities: { type: 'array', - description: 'Deprecated: replaced by app.bsky.richtext.facet.', + description: 'DEPRECATED: replaced by app.bsky.richtext.facet.', items: { type: 'ref', ref: 'lex:app.bsky.feed.post#entity', @@ -6616,6 +6846,8 @@ export const schemaDict = { }, facets: { type: 'array', + description: + 'Annotations of text (mentions, URLs, hashtags, etc)', items: { type: 'ref', ref: 'lex:app.bsky.richtext.facet', @@ -6636,6 +6868,8 @@ export const schemaDict = { }, langs: { type: 'array', + description: + 'Indicates human language of post primary text content.', maxLength: 3, items: { type: 'string', @@ -6644,21 +6878,26 @@ export const schemaDict = { }, labels: { type: 'union', + description: + 'Self-label values for this post. Effectively content warnings.', refs: ['lex:com.atproto.label.defs#selfLabels'], }, tags: { type: 'array', + description: + 'Additional hashtags, in addition to any included in post text and facets.', maxLength: 8, items: { type: 'string', maxLength: 640, maxGraphemes: 64, }, - description: 'Additional non-inline tags describing this post.', }, createdAt: { type: 'string', format: 'datetime', + description: + 'Client-declared timestamp when this post was originally created.', }, }, }, @@ -6718,7 +6957,8 @@ export const schemaDict = { id: 'app.bsky.feed.repost', defs: { main: { - description: 'A declaration of a repost.', + description: + "Record representing a 'repost' of an existing Bluesky post.", type: 'record', key: 'tid', record: { @@ -6744,7 +6984,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Find posts matching search criteria.', + description: + 'Find posts matching search criteria, returning views of those posts.', parameters: { type: 'params', required: ['q'], @@ -6807,7 +7048,7 @@ export const schemaDict = { type: 'record', key: 'tid', description: - "Defines interaction gating rules for a thread. The rkey of the threadgate record should match the rkey of the thread's root post.", + "Record defining interaction gating rules for a thread (aka, reply controls). The record key (rkey) of the threadgate record must match the record key of the thread's root post, and that record must be in the same repository..", record: { type: 'object', required: ['post', 'createdAt'], @@ -6815,6 +7056,7 @@ export const schemaDict = { post: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the post record.', }, allow: { type: 'array', @@ -6864,7 +7106,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a block.', + description: + "Record declaring a 'block' relationship against another account. NOTE: blocks are public in Bluesky; see blog posts for details.", key: 'tid', record: { type: 'object', @@ -6873,6 +7116,7 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'DID of the account to be blocked.', }, createdAt: { type: 'string', @@ -7061,7 +7305,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a social follow.', + description: + "Record declaring a social 'follow' relationship of another account. Duplicate follows will be ignored by the AppView.", key: 'tid', record: { type: 'object', @@ -7086,7 +7331,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of who the actor is blocking.', + description: + 'Enumerates which accounts the requesting account is currently blocking. Requires auth.', parameters: { type: 'params', properties: { @@ -7129,7 +7375,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: "Get a list of an actor's followers.", + description: + 'Enumerates accounts which follow a specified account (actor).', parameters: { type: 'params', required: ['actor'], @@ -7181,7 +7428,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of who the actor follows.', + description: + 'Enumerates accounts which a specified account (actor) follows.', parameters: { type: 'params', required: ['actor'], @@ -7233,7 +7481,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of actors.', + description: + "Gets a 'view' (with additional context) of a specified list.", parameters: { type: 'params', required: ['list'], @@ -7241,6 +7490,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) of the list record to hydrate.', }, limit: { type: 'integer', @@ -7285,7 +7535,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get lists that the actor is blocking.', + description: + 'Get mod lists that the requesting account (actor) is blocking. Requires auth.', parameters: { type: 'params', properties: { @@ -7328,7 +7579,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get lists that the actor is muting.', + description: + 'Enumerates mod lists that the requesting account (actor) currently has muted. Requires auth.', parameters: { type: 'params', properties: { @@ -7371,7 +7623,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of lists that belong to an actor.', + description: + 'Enumerates the lists created by a specified account (actor).', parameters: { type: 'params', required: ['actor'], @@ -7379,6 +7632,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'The account (actor) to enumerate lists from.', }, limit: { type: 'integer', @@ -7419,7 +7673,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of who the actor mutes.', + description: + 'Enumerates accounts that the requesting account (actor) currently has muted. Requires auth.', parameters: { type: 'params', properties: { @@ -7463,7 +7718,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Enumerates public relationships between one account, and a list of other accounts', + 'Enumerates public relationships between one account, and a list of other accounts. Does not require auth.', parameters: { type: 'params', required: ['actor'], @@ -7471,9 +7726,12 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Primary account requesting relationships for.', }, others: { type: 'array', + description: + "List of 'other' accounts to be related back to the primary.", maxLength: 30, items: { type: 'string', @@ -7521,7 +7779,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get suggested follows related to a given actor.', + description: + 'Enumerates follows similar to a given account (actor). Expected use is to recommend additional accounts immediately after following one account.', parameters: { type: 'params', required: ['actor'], @@ -7557,7 +7816,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a list of actors.', + description: + 'Record representing a list of accounts (actors). Scope includes both moderation-oriented lists and curration-oriented lists.', key: 'tid', record: { type: 'object', @@ -7565,12 +7825,15 @@ export const schemaDict = { properties: { purpose: { type: 'ref', + description: + 'Defines the purpose of the list (aka, moderation-oriented or curration-oriented)', ref: 'lex:app.bsky.graph.defs#listPurpose', }, name: { type: 'string', maxLength: 64, minLength: 1, + description: 'Display name for list; can not be empty.', }, description: { type: 'string', @@ -7608,7 +7871,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A block of an entire list of actors.', + description: + 'Record representing a block relationship against an entire an entire list of accounts (actors).', key: 'tid', record: { type: 'object', @@ -7617,6 +7881,7 @@ export const schemaDict = { subject: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the mod list record.', }, createdAt: { type: 'string', @@ -7633,7 +7898,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'An item under a declared list of actors.', + description: + "Record representing an account's inclusion on a specific list. The AppView will ignore duplicate listitem records.", key: 'tid', record: { type: 'object', @@ -7642,10 +7908,13 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'The account which is included on the list.', }, list: { type: 'string', format: 'at-uri', + description: + 'Reference (AT-URI) to the list record (app.bsky.graph.list).', }, createdAt: { type: 'string', @@ -7662,7 +7931,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Mute an actor by DID or handle.', + description: + 'Creates a mute relationship for the specified account. Mutes are private in Bluesky. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7685,7 +7955,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Mute a list of actors.', + description: + 'Creates a mute relationship for the specified list of accounts. Mutes are private in Bluesky. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7708,7 +7979,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Unmute an actor by DID or handle.', + description: 'Unmutes the specified account. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7731,7 +8002,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Unmute a list of actors.', + description: 'Unmutes the specified list of accounts. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7754,7 +8025,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get the count of unread notifications.', + description: + 'Count the number of unread notifications for the requesting account. Requires auth.', parameters: { type: 'params', properties: { @@ -7785,7 +8057,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of notifications.', + description: + 'Enumerate notifications for the requesting account. Requires auth.', parameters: { type: 'params', properties: { @@ -7896,7 +8169,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Register for push notifications with a service.', + description: + 'Register to receive push notifications, via a specified service, for the requesting account. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7929,7 +8203,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Notify server that the user has seen notifications.', + description: + 'Notify server that the requesting account has seen notifications. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7952,6 +8227,7 @@ export const schemaDict = { defs: { main: { type: 'object', + description: 'Annotation of a sub-string within rich text.', required: ['index', 'features'], properties: { index: { @@ -7973,7 +8249,8 @@ export const schemaDict = { }, mention: { type: 'object', - description: 'A facet feature for actor mentions.', + description: + "Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID.", required: ['did'], properties: { did: { @@ -7984,7 +8261,8 @@ export const schemaDict = { }, link: { type: 'object', - description: 'A facet feature for links.', + description: + 'Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.', required: ['uri'], properties: { uri: { @@ -7995,7 +8273,8 @@ export const schemaDict = { }, tag: { type: 'object', - description: 'A hashtag.', + description: + "Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').", required: ['tag'], properties: { tag: { @@ -8008,7 +8287,7 @@ export const schemaDict = { byteSlice: { type: 'object', description: - 'A text segment. Start is inclusive, end is exclusive. Indices are for utf8-encoded strings.', + 'Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.', required: ['byteStart', 'byteEnd'], properties: { byteStart: { diff --git a/packages/api/src/client/types/app/bsky/actor/defs.ts b/packages/api/src/client/types/app/bsky/actor/defs.ts index 5c1791e6130..5f493576334 100644 --- a/packages/api/src/client/types/app/bsky/actor/defs.ts +++ b/packages/api/src/client/types/app/bsky/actor/defs.ts @@ -82,6 +82,7 @@ export function validateProfileViewDetailed(v: unknown): ValidationResult { return lexicons.validate('app.bsky.actor.defs#profileViewDetailed', v) } +/** Metadata about the requesting account's relationship with the subject account. Only has meaningful content for authed requests. */ export interface ViewerState { muted?: boolean mutedByList?: AppBskyGraphDefs.ListViewBasic @@ -154,6 +155,7 @@ export function validateContentLabelPref(v: unknown): ValidationResult { export interface SavedFeedsPref { pinned: string[] saved: string[] + timelineIndex?: number [k: string]: unknown } diff --git a/packages/api/src/client/types/app/bsky/actor/getProfile.ts b/packages/api/src/client/types/app/bsky/actor/getProfile.ts index 47e36fe974a..bbd88c30a7b 100644 --- a/packages/api/src/client/types/app/bsky/actor/getProfile.ts +++ b/packages/api/src/client/types/app/bsky/actor/getProfile.ts @@ -9,6 +9,7 @@ import { CID } from 'multiformats/cid' import * as AppBskyActorDefs from './defs' export interface QueryParams { + /** Handle or DID of account to fetch profile of. */ actor: string } diff --git a/packages/api/src/client/types/app/bsky/actor/profile.ts b/packages/api/src/client/types/app/bsky/actor/profile.ts index fa36f4298f1..a0c51e060c5 100644 --- a/packages/api/src/client/types/app/bsky/actor/profile.ts +++ b/packages/api/src/client/types/app/bsky/actor/profile.ts @@ -9,8 +9,11 @@ import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs' export interface Record { displayName?: string + /** Free-form profile description text. */ description?: string + /** Small image to be displayed next to posts from account. AKA, 'profile picture' */ avatar?: BlobRef + /** Larger horizontal image to display behind profile view. */ banner?: BlobRef labels?: | ComAtprotoLabelDefs.SelfLabels diff --git a/packages/api/src/client/types/app/bsky/embed/external.ts b/packages/api/src/client/types/app/bsky/embed/external.ts index 271c103dbba..5832cbb3987 100644 --- a/packages/api/src/client/types/app/bsky/embed/external.ts +++ b/packages/api/src/client/types/app/bsky/embed/external.ts @@ -6,6 +6,7 @@ import { isObj, hasProp } from '../../../../util' import { lexicons } from '../../../../lexicons' import { CID } from 'multiformats/cid' +/** A representation of some externally linked content (eg, a URL and 'card'), embedded in a Bluesky record (eg, a post). */ export interface Main { external: External [k: string]: unknown diff --git a/packages/api/src/client/types/app/bsky/embed/images.ts b/packages/api/src/client/types/app/bsky/embed/images.ts index 77909a4b3b0..ddfdf4c156c 100644 --- a/packages/api/src/client/types/app/bsky/embed/images.ts +++ b/packages/api/src/client/types/app/bsky/embed/images.ts @@ -26,6 +26,7 @@ export function validateMain(v: unknown): ValidationResult { export interface Image { image: BlobRef + /** Alt text description of the image, for accessibility. */ alt: string aspectRatio?: AspectRatio [k: string]: unknown @@ -76,8 +77,11 @@ export function validateView(v: unknown): ValidationResult { } export interface ViewImage { + /** Fully-qualified URL where a thumbnail of the image can be fetched. For example, CDN location provided by the App View. */ thumb: string + /** 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. */ fullsize: string + /** Alt text description of the image, for accessibility. */ alt: string aspectRatio?: AspectRatio [k: string]: unknown diff --git a/packages/api/src/client/types/app/bsky/embed/record.ts b/packages/api/src/client/types/app/bsky/embed/record.ts index caee8f08cdd..388687fd665 100644 --- a/packages/api/src/client/types/app/bsky/embed/record.ts +++ b/packages/api/src/client/types/app/bsky/embed/record.ts @@ -57,6 +57,7 @@ export interface ViewRecord { uri: string cid: string author: AppBskyActorDefs.ProfileViewBasic + /** The record data itself. */ value: {} labels?: ComAtprotoLabelDefs.Label[] embeds?: ( diff --git a/packages/api/src/client/types/app/bsky/feed/defs.ts b/packages/api/src/client/types/app/bsky/feed/defs.ts index 82cbfd9951a..949b8fb975e 100644 --- a/packages/api/src/client/types/app/bsky/feed/defs.ts +++ b/packages/api/src/client/types/app/bsky/feed/defs.ts @@ -45,6 +45,7 @@ export function validatePostView(v: unknown): ValidationResult { return lexicons.validate('app.bsky.feed.defs#postView', v) } +/** Metadata about the requesting account's relationship with the subject content. Only has meaningful content for authed requests. */ export interface ViewerState { repost?: string like?: string diff --git a/packages/api/src/client/types/app/bsky/feed/getAuthorFeed.ts b/packages/api/src/client/types/app/bsky/feed/getAuthorFeed.ts index a070dad6ff7..3f498e49514 100644 --- a/packages/api/src/client/types/app/bsky/feed/getAuthorFeed.ts +++ b/packages/api/src/client/types/app/bsky/feed/getAuthorFeed.ts @@ -12,6 +12,7 @@ export interface QueryParams { actor: string limit?: number cursor?: string + /** Combinations of post/repost types to include in response. */ filter?: | 'posts_with_replies' | 'posts_no_replies' diff --git a/packages/api/src/client/types/app/bsky/feed/getFeedGenerator.ts b/packages/api/src/client/types/app/bsky/feed/getFeedGenerator.ts index a2f9b405c97..f08c9b59340 100644 --- a/packages/api/src/client/types/app/bsky/feed/getFeedGenerator.ts +++ b/packages/api/src/client/types/app/bsky/feed/getFeedGenerator.ts @@ -9,6 +9,7 @@ import { CID } from 'multiformats/cid' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** AT-URI of the feed generator record. */ feed: string } @@ -16,7 +17,9 @@ export type InputSchema = undefined export interface OutputSchema { view: AppBskyFeedDefs.GeneratorView + /** Indicates whether the feed generator service has been online recently, or else seems to be inactive. */ isOnline: boolean + /** Indicates whether the feed generator service is compatible with the record declaration. */ isValid: boolean [k: string]: unknown } diff --git a/packages/api/src/client/types/app/bsky/feed/getFeedSkeleton.ts b/packages/api/src/client/types/app/bsky/feed/getFeedSkeleton.ts index 0aa325d7fec..1426469c84d 100644 --- a/packages/api/src/client/types/app/bsky/feed/getFeedSkeleton.ts +++ b/packages/api/src/client/types/app/bsky/feed/getFeedSkeleton.ts @@ -9,6 +9,7 @@ import { CID } from 'multiformats/cid' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Reference to feed generator record describing the specific feed being requested. */ feed: string limit?: number cursor?: string diff --git a/packages/api/src/client/types/app/bsky/feed/getLikes.ts b/packages/api/src/client/types/app/bsky/feed/getLikes.ts index d78047feb6e..9725ef065d9 100644 --- a/packages/api/src/client/types/app/bsky/feed/getLikes.ts +++ b/packages/api/src/client/types/app/bsky/feed/getLikes.ts @@ -9,7 +9,9 @@ import { CID } from 'multiformats/cid' import * as AppBskyActorDefs from '../actor/defs' export interface QueryParams { + /** AT-URI of the subject (eg, a post record). */ uri: string + /** CID of the subject record (aka, specific version of record), to filter likes. */ cid?: string limit?: number cursor?: string diff --git a/packages/api/src/client/types/app/bsky/feed/getListFeed.ts b/packages/api/src/client/types/app/bsky/feed/getListFeed.ts index 511e9526c6d..6b4156ddda9 100644 --- a/packages/api/src/client/types/app/bsky/feed/getListFeed.ts +++ b/packages/api/src/client/types/app/bsky/feed/getListFeed.ts @@ -9,6 +9,7 @@ import { CID } from 'multiformats/cid' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Reference (AT-URI) to the list record. */ list: string limit?: number cursor?: string diff --git a/packages/api/src/client/types/app/bsky/feed/getPostThread.ts b/packages/api/src/client/types/app/bsky/feed/getPostThread.ts index d3865db9ee2..d03ad7de127 100644 --- a/packages/api/src/client/types/app/bsky/feed/getPostThread.ts +++ b/packages/api/src/client/types/app/bsky/feed/getPostThread.ts @@ -9,8 +9,11 @@ import { CID } from 'multiformats/cid' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Reference (AT-URI) to post record. */ uri: string + /** How many levels of reply depth should be included in response. */ depth?: number + /** How many levels of parent (and grandparent, etc) post to include. */ parentHeight?: number } diff --git a/packages/api/src/client/types/app/bsky/feed/getPosts.ts b/packages/api/src/client/types/app/bsky/feed/getPosts.ts index 933919bdcc1..cd932d88047 100644 --- a/packages/api/src/client/types/app/bsky/feed/getPosts.ts +++ b/packages/api/src/client/types/app/bsky/feed/getPosts.ts @@ -9,6 +9,7 @@ import { CID } from 'multiformats/cid' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** List of post AT-URIs to return hydrated views for. */ uris: string[] } diff --git a/packages/api/src/client/types/app/bsky/feed/getRepostedBy.ts b/packages/api/src/client/types/app/bsky/feed/getRepostedBy.ts index 30a1a109aaa..d27aa1dec0a 100644 --- a/packages/api/src/client/types/app/bsky/feed/getRepostedBy.ts +++ b/packages/api/src/client/types/app/bsky/feed/getRepostedBy.ts @@ -9,7 +9,9 @@ import { CID } from 'multiformats/cid' import * as AppBskyActorDefs from '../actor/defs' export interface QueryParams { + /** Reference (AT-URI) of post record */ uri: string + /** If supplied, filters to reposts of specific version (by CID) of the post record. */ cid?: string limit?: number cursor?: string diff --git a/packages/api/src/client/types/app/bsky/feed/getTimeline.ts b/packages/api/src/client/types/app/bsky/feed/getTimeline.ts index 6d8dacff99a..5ab2c7c4b1f 100644 --- a/packages/api/src/client/types/app/bsky/feed/getTimeline.ts +++ b/packages/api/src/client/types/app/bsky/feed/getTimeline.ts @@ -9,6 +9,7 @@ import { CID } from 'multiformats/cid' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Variant 'algorithm' for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism. */ algorithm?: string limit?: number cursor?: string diff --git a/packages/api/src/client/types/app/bsky/feed/post.ts b/packages/api/src/client/types/app/bsky/feed/post.ts index a3299e19035..0de5192af77 100644 --- a/packages/api/src/client/types/app/bsky/feed/post.ts +++ b/packages/api/src/client/types/app/bsky/feed/post.ts @@ -14,9 +14,11 @@ import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs' import * as ComAtprotoRepoStrongRef from '../../../com/atproto/repo/strongRef' export interface Record { + /** The primary post content. May be an empty string, if there are embeds. */ text: string - /** Deprecated: replaced by app.bsky.richtext.facet. */ + /** DEPRECATED: replaced by app.bsky.richtext.facet. */ entities?: Entity[] + /** Annotations of text (mentions, URLs, hashtags, etc) */ facets?: AppBskyRichtextFacet.Main[] reply?: ReplyRef embed?: @@ -25,12 +27,14 @@ export interface Record { | AppBskyEmbedRecord.Main | AppBskyEmbedRecordWithMedia.Main | { $type: string; [k: string]: unknown } + /** Indicates human language of post primary text content. */ langs?: string[] labels?: | ComAtprotoLabelDefs.SelfLabels | { $type: string; [k: string]: unknown } - /** Additional non-inline tags describing this post. */ + /** Additional hashtags, in addition to any included in post text and facets. */ tags?: string[] + /** Client-declared timestamp when this post was originally created. */ createdAt: string [k: string]: unknown } diff --git a/packages/api/src/client/types/app/bsky/feed/threadgate.ts b/packages/api/src/client/types/app/bsky/feed/threadgate.ts index a1afec85673..cc8c05a78ec 100644 --- a/packages/api/src/client/types/app/bsky/feed/threadgate.ts +++ b/packages/api/src/client/types/app/bsky/feed/threadgate.ts @@ -7,6 +7,7 @@ import { lexicons } from '../../../../lexicons' import { CID } from 'multiformats/cid' export interface Record { + /** Reference (AT-URI) to the post record. */ post: string allow?: ( | MentionRule diff --git a/packages/api/src/client/types/app/bsky/graph/block.ts b/packages/api/src/client/types/app/bsky/graph/block.ts index c35258d979a..f2455fc08a2 100644 --- a/packages/api/src/client/types/app/bsky/graph/block.ts +++ b/packages/api/src/client/types/app/bsky/graph/block.ts @@ -7,6 +7,7 @@ import { lexicons } from '../../../../lexicons' import { CID } from 'multiformats/cid' export interface Record { + /** DID of the account to be blocked. */ subject: string createdAt: string [k: string]: unknown diff --git a/packages/api/src/client/types/app/bsky/graph/getList.ts b/packages/api/src/client/types/app/bsky/graph/getList.ts index 13ebd9d3ae6..36c4cf0aa86 100644 --- a/packages/api/src/client/types/app/bsky/graph/getList.ts +++ b/packages/api/src/client/types/app/bsky/graph/getList.ts @@ -9,6 +9,7 @@ import { CID } from 'multiformats/cid' import * as AppBskyGraphDefs from './defs' export interface QueryParams { + /** Reference (AT-URI) of the list record to hydrate. */ list: string limit?: number cursor?: string diff --git a/packages/api/src/client/types/app/bsky/graph/getLists.ts b/packages/api/src/client/types/app/bsky/graph/getLists.ts index 80a7edfb759..644aeea3b4b 100644 --- a/packages/api/src/client/types/app/bsky/graph/getLists.ts +++ b/packages/api/src/client/types/app/bsky/graph/getLists.ts @@ -9,6 +9,7 @@ import { CID } from 'multiformats/cid' import * as AppBskyGraphDefs from './defs' export interface QueryParams { + /** The account (actor) to enumerate lists from. */ actor: string limit?: number cursor?: string diff --git a/packages/api/src/client/types/app/bsky/graph/getRelationships.ts b/packages/api/src/client/types/app/bsky/graph/getRelationships.ts index 5fce53f635c..9aa58ad2699 100644 --- a/packages/api/src/client/types/app/bsky/graph/getRelationships.ts +++ b/packages/api/src/client/types/app/bsky/graph/getRelationships.ts @@ -9,7 +9,9 @@ import { CID } from 'multiformats/cid' import * as AppBskyGraphDefs from './defs' export interface QueryParams { + /** Primary account requesting relationships for. */ actor: string + /** List of 'other' accounts to be related back to the primary. */ others?: string[] } diff --git a/packages/api/src/client/types/app/bsky/graph/list.ts b/packages/api/src/client/types/app/bsky/graph/list.ts index 4fe6dd8ed8b..fec652ccb12 100644 --- a/packages/api/src/client/types/app/bsky/graph/list.ts +++ b/packages/api/src/client/types/app/bsky/graph/list.ts @@ -11,6 +11,7 @@ import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs' export interface Record { purpose: AppBskyGraphDefs.ListPurpose + /** Display name for list; can not be empty. */ name: string description?: string descriptionFacets?: AppBskyRichtextFacet.Main[] diff --git a/packages/api/src/client/types/app/bsky/graph/listblock.ts b/packages/api/src/client/types/app/bsky/graph/listblock.ts index 770dfbb0775..e0f02be268f 100644 --- a/packages/api/src/client/types/app/bsky/graph/listblock.ts +++ b/packages/api/src/client/types/app/bsky/graph/listblock.ts @@ -7,6 +7,7 @@ import { lexicons } from '../../../../lexicons' import { CID } from 'multiformats/cid' export interface Record { + /** Reference (AT-URI) to the mod list record. */ subject: string createdAt: string [k: string]: unknown diff --git a/packages/api/src/client/types/app/bsky/graph/listitem.ts b/packages/api/src/client/types/app/bsky/graph/listitem.ts index 5059ef69c10..d4fb5631e84 100644 --- a/packages/api/src/client/types/app/bsky/graph/listitem.ts +++ b/packages/api/src/client/types/app/bsky/graph/listitem.ts @@ -7,7 +7,9 @@ import { lexicons } from '../../../../lexicons' import { CID } from 'multiformats/cid' export interface Record { + /** The account which is included on the list. */ subject: string + /** Reference (AT-URI) to the list record (app.bsky.graph.list). */ list: string createdAt: string [k: string]: unknown diff --git a/packages/api/src/client/types/app/bsky/richtext/facet.ts b/packages/api/src/client/types/app/bsky/richtext/facet.ts index 96573bb06fe..836136b7dac 100644 --- a/packages/api/src/client/types/app/bsky/richtext/facet.ts +++ b/packages/api/src/client/types/app/bsky/richtext/facet.ts @@ -6,6 +6,7 @@ import { isObj, hasProp } from '../../../../util' import { lexicons } from '../../../../lexicons' import { CID } from 'multiformats/cid' +/** Annotation of a sub-string within rich text. */ export interface Main { index: ByteSlice features: (Mention | Link | Tag | { $type: string; [k: string]: unknown })[] @@ -25,7 +26,7 @@ export function validateMain(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#main', v) } -/** A facet feature for actor mentions. */ +/** Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID. */ export interface Mention { did: string [k: string]: unknown @@ -43,7 +44,7 @@ export function validateMention(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#mention', v) } -/** A facet feature for links. */ +/** Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL. */ export interface Link { uri: string [k: string]: unknown @@ -61,7 +62,7 @@ export function validateLink(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#link', v) } -/** A hashtag. */ +/** Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags'). */ export interface Tag { tag: string [k: string]: unknown @@ -77,7 +78,7 @@ export function validateTag(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#tag', v) } -/** A text segment. Start is inclusive, end is exclusive. Indices are for utf8-encoded strings. */ +/** Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets. */ export interface ByteSlice { byteStart: number byteEnd: number diff --git a/packages/api/src/client/types/com/atproto/admin/defs.ts b/packages/api/src/client/types/com/atproto/admin/defs.ts index c0d8157e6ac..4e3d35a869f 100644 --- a/packages/api/src/client/types/com/atproto/admin/defs.ts +++ b/packages/api/src/client/types/com/atproto/admin/defs.ts @@ -156,6 +156,7 @@ export interface SubjectStatusView { /** True indicates that the a previously taken moderator action was appealed against, by the author of the content. False indicates last appeal was resolved by moderators. */ appealed?: boolean suspendUntil?: string + tags?: string[] [k: string]: unknown } @@ -720,6 +721,29 @@ export function validateModEventEmail(v: unknown): ValidationResult { return lexicons.validate('com.atproto.admin.defs#modEventEmail', v) } +/** Add/Remove a tag on a subject */ +export interface ModEventTag { + /** Tags to be added to the subject. If already exists, won't be duplicated. */ + add: string[] + /** Tags to be removed to the subject. Ignores a tag If it doesn't exist, won't be duplicated. */ + remove: string[] + /** Additional comment about added/removed tags. */ + comment?: string + [k: string]: unknown +} + +export function isModEventTag(v: unknown): v is ModEventTag { + return ( + isObj(v) && + hasProp(v, '$type') && + v.$type === 'com.atproto.admin.defs#modEventTag' + ) +} + +export function validateModEventTag(v: unknown): ValidationResult { + return lexicons.validate('com.atproto.admin.defs#modEventTag', v) +} + export interface CommunicationTemplateView { id: string /** Name of the template. */ diff --git a/packages/api/src/client/types/com/atproto/admin/emitModerationEvent.ts b/packages/api/src/client/types/com/atproto/admin/emitModerationEvent.ts index 77b460ed1ff..6e7827bdc6a 100644 --- a/packages/api/src/client/types/com/atproto/admin/emitModerationEvent.ts +++ b/packages/api/src/client/types/com/atproto/admin/emitModerationEvent.ts @@ -23,6 +23,7 @@ export interface InputSchema { | ComAtprotoAdminDefs.ModEventReverseTakedown | ComAtprotoAdminDefs.ModEventUnmute | ComAtprotoAdminDefs.ModEventEmail + | ComAtprotoAdminDefs.ModEventTag | { $type: string; [k: string]: unknown } subject: | ComAtprotoAdminDefs.RepoRef diff --git a/packages/api/src/client/types/com/atproto/admin/queryModerationEvents.ts b/packages/api/src/client/types/com/atproto/admin/queryModerationEvents.ts index 1540babae51..2dd3081ef8f 100644 --- a/packages/api/src/client/types/com/atproto/admin/queryModerationEvents.ts +++ b/packages/api/src/client/types/com/atproto/admin/queryModerationEvents.ts @@ -30,6 +30,10 @@ export interface QueryParams { addedLabels?: string[] /** If specified, only events where all of these labels were removed are returned */ removedLabels?: string[] + /** If specified, only events where all of these tags were added are returned */ + addedTags?: string[] + /** If specified, only events where all of these tags were removed are returned */ + removedTags?: string[] reportTypes?: string[] cursor?: string } diff --git a/packages/api/src/client/types/com/atproto/admin/queryModerationStatuses.ts b/packages/api/src/client/types/com/atproto/admin/queryModerationStatuses.ts index 0039016a353..c16bb94fec3 100644 --- a/packages/api/src/client/types/com/atproto/admin/queryModerationStatuses.ts +++ b/packages/api/src/client/types/com/atproto/admin/queryModerationStatuses.ts @@ -34,6 +34,8 @@ export interface QueryParams { /** Get subjects in unresolved appealed status */ appealed?: boolean limit?: number + tags?: string[] + excludeTags?: string[] cursor?: string } diff --git a/packages/api/src/client/types/com/atproto/identity/updateHandle.ts b/packages/api/src/client/types/com/atproto/identity/updateHandle.ts index 4c01e105c28..2bd2c4c9d6a 100644 --- a/packages/api/src/client/types/com/atproto/identity/updateHandle.ts +++ b/packages/api/src/client/types/com/atproto/identity/updateHandle.ts @@ -10,6 +10,7 @@ import { CID } from 'multiformats/cid' export interface QueryParams {} export interface InputSchema { + /** The new handle. */ handle: string [k: string]: unknown } diff --git a/packages/api/src/client/types/com/atproto/moderation/createReport.ts b/packages/api/src/client/types/com/atproto/moderation/createReport.ts index 826b32ff67c..7bf3cc1a380 100644 --- a/packages/api/src/client/types/com/atproto/moderation/createReport.ts +++ b/packages/api/src/client/types/com/atproto/moderation/createReport.ts @@ -14,6 +14,7 @@ export interface QueryParams {} export interface InputSchema { reasonType: ComAtprotoModerationDefs.ReasonType + /** Additional context about the content and violation. */ reason?: string subject: | ComAtprotoAdminDefs.RepoRef diff --git a/packages/api/src/client/types/com/atproto/repo/applyWrites.ts b/packages/api/src/client/types/com/atproto/repo/applyWrites.ts index f4a8a269201..df35ec7dcbf 100644 --- a/packages/api/src/client/types/com/atproto/repo/applyWrites.ts +++ b/packages/api/src/client/types/com/atproto/repo/applyWrites.ts @@ -10,11 +10,12 @@ import { CID } from 'multiformats/cid' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string - /** Flag for validating the records. */ + /** Can be set to 'false' to skip Lexicon schema validation of record data, for all operations. */ validate?: boolean writes: (Create | Update | Delete)[] + /** If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations. */ swapCommit?: string [k: string]: unknown } @@ -43,7 +44,7 @@ export function toKnownErr(e: any) { return e } -/** Create a new record. */ +/** Operation which creates a new record. */ export interface Create { collection: string rkey?: string @@ -63,7 +64,7 @@ export function validateCreate(v: unknown): ValidationResult { return lexicons.validate('com.atproto.repo.applyWrites#create', v) } -/** Update an existing record. */ +/** Operation which updates an existing record. */ export interface Update { collection: string rkey: string @@ -83,7 +84,7 @@ export function validateUpdate(v: unknown): ValidationResult { return lexicons.validate('com.atproto.repo.applyWrites#update', v) } -/** Delete an existing record. */ +/** Operation which deletes an existing record. */ export interface Delete { collection: string rkey: string diff --git a/packages/api/src/client/types/com/atproto/repo/createRecord.ts b/packages/api/src/client/types/com/atproto/repo/createRecord.ts index 2056778c71c..6b13f67db7f 100644 --- a/packages/api/src/client/types/com/atproto/repo/createRecord.ts +++ b/packages/api/src/client/types/com/atproto/repo/createRecord.ts @@ -10,15 +10,15 @@ import { CID } from 'multiformats/cid' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey?: string - /** Flag for validating the record. */ + /** Can be set to 'false' to skip Lexicon schema validation of record data. */ validate?: boolean - /** The record to create. */ + /** The record itself. Must contain a $type field. */ record: {} /** Compare and swap with the previous commit by CID. */ swapCommit?: string diff --git a/packages/api/src/client/types/com/atproto/repo/deleteRecord.ts b/packages/api/src/client/types/com/atproto/repo/deleteRecord.ts index 5bf9237abbb..54109b62f31 100644 --- a/packages/api/src/client/types/com/atproto/repo/deleteRecord.ts +++ b/packages/api/src/client/types/com/atproto/repo/deleteRecord.ts @@ -10,11 +10,11 @@ import { CID } from 'multiformats/cid' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey: string /** Compare and swap with the previous record by CID. */ swapRecord?: string diff --git a/packages/api/src/client/types/com/atproto/repo/describeRepo.ts b/packages/api/src/client/types/com/atproto/repo/describeRepo.ts index e6ecedb3297..f17a8410782 100644 --- a/packages/api/src/client/types/com/atproto/repo/describeRepo.ts +++ b/packages/api/src/client/types/com/atproto/repo/describeRepo.ts @@ -17,8 +17,11 @@ export type InputSchema = undefined export interface OutputSchema { handle: string did: string + /** The complete DID document for this account. */ didDoc: {} + /** List of all the collections (NSIDs) for which this repo contains at least one record. */ collections: string[] + /** Indicates if handle is currently valid (resolves bi-directionally) */ handleIsCorrect: boolean [k: string]: unknown } diff --git a/packages/api/src/client/types/com/atproto/repo/getRecord.ts b/packages/api/src/client/types/com/atproto/repo/getRecord.ts index 56338d016ee..a6d2bd39e8c 100644 --- a/packages/api/src/client/types/com/atproto/repo/getRecord.ts +++ b/packages/api/src/client/types/com/atproto/repo/getRecord.ts @@ -12,7 +12,7 @@ export interface QueryParams { repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey: string /** The CID of the version of the record. If not specified, then return the most recent version. */ cid?: string diff --git a/packages/api/src/client/types/com/atproto/repo/putRecord.ts b/packages/api/src/client/types/com/atproto/repo/putRecord.ts index 269ef759401..7421ee19780 100644 --- a/packages/api/src/client/types/com/atproto/repo/putRecord.ts +++ b/packages/api/src/client/types/com/atproto/repo/putRecord.ts @@ -10,17 +10,17 @@ import { CID } from 'multiformats/cid' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey: string - /** Flag for validating the record. */ + /** Can be set to 'false' to skip Lexicon schema validation of record data. */ validate?: boolean /** The record to write. */ record: {} - /** Compare and swap with the previous record by CID. */ + /** Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation */ swapRecord?: string | null /** Compare and swap with the previous commit by CID. */ swapCommit?: string diff --git a/packages/api/src/client/types/com/atproto/server/createAccount.ts b/packages/api/src/client/types/com/atproto/server/createAccount.ts index b62adf97cb1..5e36eca0ee3 100644 --- a/packages/api/src/client/types/com/atproto/server/createAccount.ts +++ b/packages/api/src/client/types/com/atproto/server/createAccount.ts @@ -11,22 +11,30 @@ export interface QueryParams {} export interface InputSchema { email?: string + /** Requested handle for the account. */ handle: string + /** Pre-existing atproto DID, being imported to a new account. */ did?: string inviteCode?: string verificationCode?: string verificationPhone?: string + /** Initial account password. May need to meet instance-specific password strength requirements. */ password?: string + /** DID PLC rotation key (aka, recovery key) to be included in PLC creation operation. */ recoveryKey?: string + /** A signed DID PLC operation to be submitted as part of importing an existing account to this instance. NOTE: this optional field may be updated when full account migration is implemented. */ plcOp?: {} [k: string]: unknown } +/** Account login session returned on successful account creation. */ export interface OutputSchema { accessJwt: string refreshJwt: string handle: string + /** The DID of the new account. */ did: string + /** Complete DID document. */ didDoc?: {} [k: string]: unknown } diff --git a/packages/api/src/client/types/com/atproto/server/createAppPassword.ts b/packages/api/src/client/types/com/atproto/server/createAppPassword.ts index d6e9ce3ddf5..8b9a5d53a7c 100644 --- a/packages/api/src/client/types/com/atproto/server/createAppPassword.ts +++ b/packages/api/src/client/types/com/atproto/server/createAppPassword.ts @@ -10,6 +10,7 @@ import { CID } from 'multiformats/cid' export interface QueryParams {} export interface InputSchema { + /** A short name for the App Password, to help distinguish them. */ name: string [k: string]: unknown } diff --git a/packages/api/src/client/types/com/atproto/server/describeServer.ts b/packages/api/src/client/types/com/atproto/server/describeServer.ts index fb6c9d5c662..5aca005ec9f 100644 --- a/packages/api/src/client/types/com/atproto/server/describeServer.ts +++ b/packages/api/src/client/types/com/atproto/server/describeServer.ts @@ -12,8 +12,11 @@ export interface QueryParams {} export type InputSchema = undefined export interface OutputSchema { + /** If true, an invite code must be supplied to create an account on this instance. */ inviteCodeRequired?: boolean + /** If true, a phone verification token must be supplied to create an account on this instance. */ phoneVerificationRequired?: boolean + /** List of domain suffixes that can be used in account handles. */ availableUserDomains: string[] links?: Links [k: string]: unknown diff --git a/packages/api/src/client/types/com/atproto/server/getAccountInviteCodes.ts b/packages/api/src/client/types/com/atproto/server/getAccountInviteCodes.ts index d019ed3fa23..5438cbc96d6 100644 --- a/packages/api/src/client/types/com/atproto/server/getAccountInviteCodes.ts +++ b/packages/api/src/client/types/com/atproto/server/getAccountInviteCodes.ts @@ -10,6 +10,7 @@ import * as ComAtprotoServerDefs from './defs' export interface QueryParams { includeUsed?: boolean + /** Controls whether any new 'earned' but not 'created' invites should be created. */ createAvailable?: boolean } diff --git a/packages/api/src/client/types/com/atproto/server/reserveSigningKey.ts b/packages/api/src/client/types/com/atproto/server/reserveSigningKey.ts index f5e515ff5cf..324dee9665a 100644 --- a/packages/api/src/client/types/com/atproto/server/reserveSigningKey.ts +++ b/packages/api/src/client/types/com/atproto/server/reserveSigningKey.ts @@ -10,13 +10,13 @@ import { CID } from 'multiformats/cid' export interface QueryParams {} export interface InputSchema { - /** The did to reserve a new did:key for */ + /** The DID to reserve a key for. */ did?: string [k: string]: unknown } export interface OutputSchema { - /** Public signing key in the form of a did:key. */ + /** The public key for the reserved signing key, in did:key serialization. */ signingKey: string [k: string]: unknown } diff --git a/packages/api/src/client/types/com/atproto/sync/getBlob.ts b/packages/api/src/client/types/com/atproto/sync/getBlob.ts index 57bc271ce5a..83d8b79ca08 100644 --- a/packages/api/src/client/types/com/atproto/sync/getBlob.ts +++ b/packages/api/src/client/types/com/atproto/sync/getBlob.ts @@ -8,7 +8,7 @@ import { lexicons } from '../../../../lexicons' import { CID } from 'multiformats/cid' export interface QueryParams { - /** The DID of the repo. */ + /** The DID of the account. */ did: string /** The CID of the blob to fetch */ cid: string diff --git a/packages/api/src/client/types/com/atproto/sync/getRecord.ts b/packages/api/src/client/types/com/atproto/sync/getRecord.ts index e7bbcf36343..1fc9a94b406 100644 --- a/packages/api/src/client/types/com/atproto/sync/getRecord.ts +++ b/packages/api/src/client/types/com/atproto/sync/getRecord.ts @@ -11,6 +11,7 @@ export interface QueryParams { /** The DID of the repo. */ did: string collection: string + /** Record Key */ rkey: string /** An optional past commit CID. */ commit?: string diff --git a/packages/api/src/client/types/com/atproto/sync/getRepo.ts b/packages/api/src/client/types/com/atproto/sync/getRepo.ts index 0a45536779e..53e0883d74e 100644 --- a/packages/api/src/client/types/com/atproto/sync/getRepo.ts +++ b/packages/api/src/client/types/com/atproto/sync/getRepo.ts @@ -10,7 +10,7 @@ import { CID } from 'multiformats/cid' export interface QueryParams { /** The DID of the repo. */ did: string - /** The revision of the repo to catch up from. */ + /** The revision ('rev') of the repo to create a diff from. */ since?: string } diff --git a/packages/api/src/client/types/com/atproto/sync/listRepos.ts b/packages/api/src/client/types/com/atproto/sync/listRepos.ts index 669dba37e85..eccf796acb6 100644 --- a/packages/api/src/client/types/com/atproto/sync/listRepos.ts +++ b/packages/api/src/client/types/com/atproto/sync/listRepos.ts @@ -38,6 +38,7 @@ export function toKnownErr(e: any) { export interface Repo { did: string + /** Current repo commit CID */ head: string rev: string [k: string]: unknown diff --git a/packages/api/src/client/types/com/atproto/sync/notifyOfUpdate.ts b/packages/api/src/client/types/com/atproto/sync/notifyOfUpdate.ts index 2b098982684..f53e4a55385 100644 --- a/packages/api/src/client/types/com/atproto/sync/notifyOfUpdate.ts +++ b/packages/api/src/client/types/com/atproto/sync/notifyOfUpdate.ts @@ -10,7 +10,7 @@ import { CID } from 'multiformats/cid' export interface QueryParams {} export interface InputSchema { - /** Hostname of the service that is notifying of update. */ + /** Hostname of the current service (usually a PDS) that is notifying of update. */ hostname: string [k: string]: unknown } diff --git a/packages/api/src/client/types/com/atproto/sync/requestCrawl.ts b/packages/api/src/client/types/com/atproto/sync/requestCrawl.ts index c07330a6fb1..089eb84e089 100644 --- a/packages/api/src/client/types/com/atproto/sync/requestCrawl.ts +++ b/packages/api/src/client/types/com/atproto/sync/requestCrawl.ts @@ -10,7 +10,7 @@ import { CID } from 'multiformats/cid' export interface QueryParams {} export interface InputSchema { - /** Hostname of the service that is requesting to be crawled. */ + /** Hostname of the current service (eg, PDS) that is requesting to be crawled. */ hostname: string [k: string]: unknown } diff --git a/packages/api/src/client/types/com/atproto/sync/subscribeRepos.ts b/packages/api/src/client/types/com/atproto/sync/subscribeRepos.ts index a4fec035874..708fc80c85b 100644 --- a/packages/api/src/client/types/com/atproto/sync/subscribeRepos.ts +++ b/packages/api/src/client/types/com/atproto/sync/subscribeRepos.ts @@ -7,21 +7,29 @@ import { isObj, hasProp } from '../../../../util' import { lexicons } from '../../../../lexicons' import { CID } from 'multiformats/cid' +/** Represents an update of repository state. Note that empty commits are allowed, which include no repo data changes, but an update to rev and signature. */ export interface Commit { + /** The stream sequence number of this message. */ seq: number + /** DEPRECATED -- unused */ rebase: boolean + /** Indicates that this commit contained too many ops, or data size was too large. Consumers will need to make a separate request to get missing data. */ tooBig: boolean + /** The repo this event comes from. */ repo: string + /** Repo commit object CID. */ commit: CID + /** DEPRECATED -- unused. WARNING -- nullable and optional; stick with optional to ensure golang interoperability. */ prev?: CID | null - /** The rev of the emitted commit. */ + /** The rev of the emitted commit. Note that this information is also in the commit object included in blocks, unless this is a tooBig event. */ rev: string - /** The rev of the last emitted commit from this repo. */ + /** The rev of the last emitted commit from this repo (if any). */ since: string | null - /** CAR file containing relevant blocks. */ + /** CAR file containing relevant blocks, as a diff since the previous repo state. */ blocks: Uint8Array ops: RepoOp[] blobs: CID[] + /** Timestamp of when this message was originally broadcast. */ time: string [k: string]: unknown } @@ -38,6 +46,7 @@ export function validateCommit(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#commit', v) } +/** Represents an update of the account's handle, or transition to/from invalid state. */ export interface Handle { seq: number did: string @@ -58,6 +67,7 @@ export function validateHandle(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#handle', v) } +/** Represents an account moving from one PDS instance to another. NOTE: not implemented; full account migration may introduce a new message instead. */ export interface Migrate { seq: number did: string @@ -78,6 +88,7 @@ export function validateMigrate(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#migrate', v) } +/** Indicates that an account has been deleted. */ export interface Tombstone { seq: number did: string @@ -115,10 +126,11 @@ export function validateInfo(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#info', v) } -/** A repo operation, ie a write of a single record. For creates and updates, CID is the record's CID as of this operation. For deletes, it's null. */ +/** A repo operation, ie a mutation of a single record. */ export interface RepoOp { action: 'create' | 'update' | 'delete' | (string & {}) path: string + /** For creates and updates, the new record CID. For deletions, null. */ cid: CID | null [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/lexicons.ts b/packages/bsky/src/lexicon/lexicons.ts index 9db3be4f817..f3490b79dfd 100644 --- a/packages/bsky/src/lexicon/lexicons.ts +++ b/packages/bsky/src/lexicon/lexicons.ts @@ -303,6 +303,12 @@ export const schemaDict = { type: 'string', format: 'datetime', }, + tags: { + type: 'array', + items: { + type: 'string', + }, + }, }, }, reportViewDetail: { @@ -897,6 +903,33 @@ export const schemaDict = { }, }, }, + modEventTag: { + type: 'object', + description: 'Add/Remove a tag on a subject', + required: ['add', 'remove'], + properties: { + add: { + type: 'array', + items: { + type: 'string', + }, + description: + "Tags to be added to the subject. If already exists, won't be duplicated.", + }, + remove: { + type: 'array', + items: { + type: 'string', + }, + description: + "Tags to be removed to the subject. Ignores a tag If it doesn't exist, won't be duplicated.", + }, + comment: { + type: 'string', + description: 'Additional comment about added/removed tags.', + }, + }, + }, communicationTemplateView: { type: 'object', required: [ @@ -1075,6 +1108,7 @@ export const schemaDict = { 'lex:com.atproto.admin.defs#modEventReverseTakedown', 'lex:com.atproto.admin.defs#modEventUnmute', 'lex:com.atproto.admin.defs#modEventEmail', + 'lex:com.atproto.admin.defs#modEventTag', ], }, subject: { @@ -1503,6 +1537,22 @@ export const schemaDict = { description: 'If specified, only events where all of these labels were removed are returned', }, + addedTags: { + type: 'array', + items: { + type: 'string', + }, + description: + 'If specified, only events where all of these tags were added are returned', + }, + removedTags: { + type: 'array', + items: { + type: 'string', + }, + description: + 'If specified, only events where all of these tags were removed are returned', + }, reportTypes: { type: 'array', items: { @@ -1620,6 +1670,18 @@ export const schemaDict = { maximum: 100, default: 50, }, + tags: { + type: 'array', + items: { + type: 'string', + }, + }, + excludeTags: { + type: 'array', + items: { + type: 'string', + }, + }, cursor: { type: 'string', }, @@ -1912,7 +1974,7 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Provides the DID of a repo.', + description: 'Resolves a handle (domain name) to a DID.', parameters: { type: 'params', required: ['handle'], @@ -1946,7 +2008,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Updates the handle of the account.', + description: + "Updates the current account's handle. Verifies handle validity, and updates did:plc document if necessary. Implemented by PDS, and requires auth.", input: { encoding: 'application/json', schema: { @@ -1956,6 +2019,7 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'The new handle.', }, }, }, @@ -2046,7 +2110,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Find labels relevant to the provided URI patterns.', + description: + 'Find labels relevant to the provided AT-URI patterns. Public endpoint for moderation services, though may return different or additional results with auth.', parameters: { type: 'params', required: ['uriPatterns'], @@ -2107,13 +2172,14 @@ export const schemaDict = { defs: { main: { type: 'subscription', - description: 'Subscribe to label updates.', + description: + 'Subscribe to stream of labels (and negations). Public endpoint implemented by mod services. Uses same sequencing scheme as repo event stream.', parameters: { type: 'params', properties: { cursor: { type: 'integer', - description: 'The last known event to backfill from.', + description: 'The last known event seq number to backfill from.', }, }, }, @@ -2169,7 +2235,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Report a repo or a record.', + description: + 'Submit a moderation report regarding an atproto account or record. Implemented by moderation services (with PDS proxying), and requires auth.', input: { encoding: 'application/json', schema: { @@ -2178,10 +2245,14 @@ export const schemaDict = { properties: { reasonType: { type: 'ref', + description: + 'Indicates the broad category of violation the report is for.', ref: 'lex:com.atproto.moderation.defs#reasonType', }, reason: { type: 'string', + description: + 'Additional context about the content and violation.', }, subject: { type: 'union', @@ -2292,7 +2363,7 @@ export const schemaDict = { main: { type: 'procedure', description: - 'Apply a batch transaction of creates, updates, and deletes.', + 'Apply a batch transaction of repository creates, updates, and deletes. Requires auth, implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2302,12 +2373,14 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, validate: { type: 'boolean', default: true, - description: 'Flag for validating the records.', + description: + "Can be set to 'false' to skip Lexicon schema validation of record data, for all operations.", }, writes: { type: 'array', @@ -2323,6 +2396,8 @@ export const schemaDict = { }, swapCommit: { type: 'string', + description: + 'If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations.', format: 'cid', }, }, @@ -2331,12 +2406,14 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that the 'swapCommit' parameter did not match current commit.", }, ], }, create: { type: 'object', - description: 'Create a new record.', + description: 'Operation which creates a new record.', required: ['collection', 'value'], properties: { collection: { @@ -2354,7 +2431,7 @@ export const schemaDict = { }, update: { type: 'object', - description: 'Update an existing record.', + description: 'Operation which updates an existing record.', required: ['collection', 'rkey', 'value'], properties: { collection: { @@ -2371,7 +2448,7 @@ export const schemaDict = { }, delete: { type: 'object', - description: 'Delete an existing record.', + description: 'Operation which deletes an existing record.', required: ['collection', 'rkey'], properties: { collection: { @@ -2391,7 +2468,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Create a new record.', + description: + 'Create a single new repository record. Requires auth, implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2401,7 +2479,8 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, collection: { type: 'string', @@ -2410,17 +2489,18 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', maxLength: 15, }, validate: { type: 'boolean', default: true, - description: 'Flag for validating the record.', + description: + "Can be set to 'false' to skip Lexicon schema validation of record data.", }, record: { type: 'unknown', - description: 'The record to create.', + description: 'The record itself. Must contain a $type field.', }, swapCommit: { type: 'string', @@ -2451,6 +2531,8 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that 'swapCommit' didn't match current repo commit.", }, ], }, @@ -2462,7 +2544,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: "Delete a record, or ensure it doesn't exist.", + description: + "Delete a repository record, or ensure it doesn't exist. Requires auth, implemented by PDS.", input: { encoding: 'application/json', schema: { @@ -2472,7 +2555,8 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, collection: { type: 'string', @@ -2481,7 +2565,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, swapRecord: { type: 'string', @@ -2513,7 +2597,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Get information about the repo, including the list of collections.', + 'Get information about an account and repository, including the list of collections. Does not require auth.', parameters: { type: 'params', required: ['repo'], @@ -2547,9 +2631,12 @@ export const schemaDict = { }, didDoc: { type: 'unknown', + description: 'The complete DID document for this account.', }, collections: { type: 'array', + description: + 'List of all the collections (NSIDs) for which this repo contains at least one record.', items: { type: 'string', format: 'nsid', @@ -2557,6 +2644,8 @@ export const schemaDict = { }, handleIsCorrect: { type: 'boolean', + description: + 'Indicates if handle is currently valid (resolves bi-directionally)', }, }, }, @@ -2570,7 +2659,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a record.', + description: + 'Get a single record from a repository. Does not require auth.', parameters: { type: 'params', required: ['repo', 'collection', 'rkey'], @@ -2587,7 +2677,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, cid: { type: 'string', @@ -2626,7 +2716,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'List a range of records in a collection.', + description: + 'List a range of records in a repository, matching a specific collection. Does not require auth.', parameters: { type: 'params', required: ['repo', 'collection'], @@ -2712,7 +2803,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Write a record, creating or updating it as needed.', + description: + 'Write a repository record, creating or updating it as needed. Requires auth, implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2723,7 +2815,8 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, collection: { type: 'string', @@ -2732,13 +2825,14 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', maxLength: 15, }, validate: { type: 'boolean', default: true, - description: 'Flag for validating the record.', + description: + "Can be set to 'false' to skip Lexicon schema validation of record data.", }, record: { type: 'unknown', @@ -2748,7 +2842,7 @@ export const schemaDict = { type: 'string', format: 'cid', description: - 'Compare and swap with the previous record by CID.', + 'Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation', }, swapCommit: { type: 'string', @@ -2812,7 +2906,7 @@ export const schemaDict = { main: { type: 'procedure', description: - 'Upload a new blob to be added to repo in a later request.', + 'Upload a new blob, to be referenced from a repository record. The blob will be deleted if it is not referenced within a time window (eg, minutes). Blob restrictions (mimetype, size, etc) are enforced when the reference is created. Requires auth, implemented by PDS.', input: { encoding: '*/*', }, @@ -2877,7 +2971,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Create an account.', + description: 'Create an account. Implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2890,10 +2984,13 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'Requested handle for the account.', }, did: { type: 'string', format: 'did', + description: + 'Pre-existing atproto DID, being imported to a new account.', }, inviteCode: { type: 'string', @@ -2906,12 +3003,18 @@ export const schemaDict = { }, password: { type: 'string', + description: + 'Initial account password. May need to meet instance-specific password strength requirements.', }, recoveryKey: { type: 'string', + description: + 'DID PLC rotation key (aka, recovery key) to be included in PLC creation operation.', }, plcOp: { type: 'unknown', + description: + 'A signed DID PLC operation to be submitted as part of importing an existing account to this instance. NOTE: this optional field may be updated when full account migration is implemented.', }, }, }, @@ -2920,6 +3023,8 @@ export const schemaDict = { encoding: 'application/json', schema: { type: 'object', + description: + 'Account login session returned on successful account creation.', required: ['accessJwt', 'refreshJwt', 'handle', 'did'], properties: { accessJwt: { @@ -2935,9 +3040,11 @@ export const schemaDict = { did: { type: 'string', format: 'did', + description: 'The DID of the new account.', }, didDoc: { type: 'unknown', + description: 'Complete DID document.', }, }, }, @@ -2983,6 +3090,8 @@ export const schemaDict = { properties: { name: { type: 'string', + description: + 'A short name for the App Password, to help distinguish them.', }, }, }, @@ -3250,7 +3359,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: "Delete an actor's account with a token and password.", + description: + "Delete an actor's account with a token and password. Can only be called after requesting a deletion token. Requires auth.", input: { encoding: 'application/json', schema: { @@ -3287,7 +3397,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Delete the current session.', + description: 'Delete the current session. Requires auth.', }, }, }, @@ -3298,7 +3408,7 @@ export const schemaDict = { main: { type: 'query', description: - "Get a document describing the service's accounts configuration.", + "Describes the server's account creation requirements and capabilities. Implemented by PDS.", output: { encoding: 'application/json', schema: { @@ -3307,18 +3417,25 @@ export const schemaDict = { properties: { inviteCodeRequired: { type: 'boolean', + description: + 'If true, an invite code must be supplied to create an account on this instance.', }, phoneVerificationRequired: { type: 'boolean', + description: + 'If true, a phone verification token must be supplied to create an account on this instance.', }, availableUserDomains: { type: 'array', + description: + 'List of domain suffixes that can be used in account handles.', items: { type: 'string', }, }, links: { type: 'ref', + description: 'URLs of service policy documents.', ref: 'lex:com.atproto.server.describeServer#links', }, }, @@ -3344,7 +3461,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get all invite codes for a given account.', + description: + 'Get all invite codes for the current account. Requires auth.', parameters: { type: 'params', properties: { @@ -3355,6 +3473,8 @@ export const schemaDict = { createAvailable: { type: 'boolean', default: true, + description: + "Controls whether any new 'earned' but not 'created' invites should be created.", }, }, }, @@ -3388,7 +3508,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get information about the current session.', + description: + 'Get information about the current auth session. Requires auth.', output: { encoding: 'application/json', schema: { @@ -3468,7 +3589,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Refresh an authentication session.', + description: + "Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt').", output: { encoding: 'application/json', schema: { @@ -3574,7 +3696,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Reserve a repo signing key for account creation.', + description: + 'Reserve a repo signing key, for use with account creation. Necessary so that a DID PLC update operation can be constructed during an account migraiton. Public and does not require auth; implemented by PDS. NOTE: this endpoint may change when full account migration is implemented.', input: { encoding: 'application/json', schema: { @@ -3582,7 +3705,8 @@ export const schemaDict = { properties: { did: { type: 'string', - description: 'The did to reserve a new did:key for', + format: 'did', + description: 'The DID to reserve a key for.', }, }, }, @@ -3595,7 +3719,8 @@ export const schemaDict = { properties: { signingKey: { type: 'string', - description: 'Public signing key in the form of a did:key.', + description: + 'The public key for the reserved signing key, in did:key serialization.', }, }, }, @@ -3702,7 +3827,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a blob associated with a given repo.', + description: + 'Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS.', parameters: { type: 'params', required: ['did', 'cid'], @@ -3710,7 +3836,7 @@ export const schemaDict = { did: { type: 'string', format: 'did', - description: 'The DID of the repo.', + description: 'The DID of the account.', }, cid: { type: 'string', @@ -3731,7 +3857,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get blocks from a given repo.', + description: + 'Get data blocks from a given repo, by CID. For example, intermediate MST nodes, or records. Does not require auth; implemented by PDS.', parameters: { type: 'params', required: ['did', 'cids'], @@ -3826,7 +3953,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get the current commit CID & revision of the repo.', + description: + 'Get the current commit CID & revision of the specified repo. Does not require auth.', parameters: { type: 'params', required: ['did'], @@ -3869,7 +3997,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Get blocks needed for existence or non-existence of record.', + 'Get data blocks needed to prove the existence or non-existence of record in the current version of repo. Does not require auth.', parameters: { type: 'params', required: ['did', 'collection', 'rkey'], @@ -3885,6 +4013,7 @@ export const schemaDict = { }, rkey: { type: 'string', + description: 'Record Key', }, commit: { type: 'string', @@ -3906,7 +4035,7 @@ export const schemaDict = { main: { type: 'query', description: - "Gets the DID's repo, optionally catching up from a specific revision.", + "Download a repository export as CAR file. Optionally only a 'diff' since a previous revision. Does not require auth; implemented by PDS.", parameters: { type: 'params', required: ['did'], @@ -3918,7 +4047,8 @@ export const schemaDict = { }, since: { type: 'string', - description: 'The revision of the repo to catch up from.', + description: + "The revision ('rev') of the repo to create a diff from.", }, }, }, @@ -3934,7 +4064,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'List blob CIDs since some revision.', + description: + 'List blob CIDso for an account, since some repo revision. Does not require auth; implemented by PDS.', parameters: { type: 'params', required: ['did'], @@ -3987,7 +4118,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'List DIDs and root CIDs of hosted repos.', + description: + 'Enumerates all the DID, rev, and commit CID for all repos hosted by this service. Does not require auth; implemented by PDS and Relay.', parameters: { type: 'params', properties: { @@ -4033,6 +4165,7 @@ export const schemaDict = { head: { type: 'string', format: 'cid', + description: 'Current repo commit CID', }, rev: { type: 'string', @@ -4048,7 +4181,7 @@ export const schemaDict = { main: { type: 'procedure', description: - 'Notify a crawling service of a recent update; often when a long break between updates causes the connection with the crawling service to break.', + 'Notify a crawling service of a recent update, and that crawling should resume. Intended use is after a gap between repo stream events caused the crawling service to disconnect. Does not require auth; implemented by Relay.', input: { encoding: 'application/json', schema: { @@ -4058,7 +4191,7 @@ export const schemaDict = { hostname: { type: 'string', description: - 'Hostname of the service that is notifying of update.', + 'Hostname of the current service (usually a PDS) that is notifying of update.', }, }, }, @@ -4072,7 +4205,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Request a service to persistently crawl hosted repos.', + description: + 'Request a service to persistently crawl hosted repos. Expected use is new PDS instances declaring their existence to Relays. Does not require auth.', input: { encoding: 'application/json', schema: { @@ -4082,7 +4216,7 @@ export const schemaDict = { hostname: { type: 'string', description: - 'Hostname of the service that is requesting to be crawled.', + 'Hostname of the current service (eg, PDS) that is requesting to be crawled.', }, }, }, @@ -4096,13 +4230,14 @@ export const schemaDict = { defs: { main: { type: 'subscription', - description: 'Subscribe to repo updates.', + description: + 'Repository event stream, aka Firehose endpoint. Outputs repo commits with diff data, and identity update events, for all repositories on the current server. See the atproto specifications for details around stream sequencing, repo versioning, CAR diff format, and more. Public and does not require auth; implemented by PDS and Relay.', parameters: { type: 'params', properties: { cursor: { type: 'integer', - description: 'The last known event to backfill from.', + description: 'The last known event seq number to backfill from.', }, }, }, @@ -4124,11 +4259,15 @@ export const schemaDict = { }, { name: 'ConsumerTooSlow', + description: + 'If the consumer of the stream can not keep up with events, and a backlog gets too large, the server will drop the connection.', }, ], }, commit: { type: 'object', + description: + 'Represents an update of repository state. Note that empty commits are allowed, which include no repo data changes, but an update to rev and signature.', required: [ 'seq', 'rebase', @@ -4146,34 +4285,45 @@ export const schemaDict = { properties: { seq: { type: 'integer', + description: 'The stream sequence number of this message.', }, rebase: { type: 'boolean', + description: 'DEPRECATED -- unused', }, tooBig: { type: 'boolean', + description: + 'Indicates that this commit contained too many ops, or data size was too large. Consumers will need to make a separate request to get missing data.', }, repo: { type: 'string', format: 'did', + description: 'The repo this event comes from.', }, commit: { type: 'cid-link', + description: 'Repo commit object CID.', }, prev: { type: 'cid-link', + description: + 'DEPRECATED -- unused. WARNING -- nullable and optional; stick with optional to ensure golang interoperability.', }, rev: { type: 'string', - description: 'The rev of the emitted commit.', + description: + 'The rev of the emitted commit. Note that this information is also in the commit object included in blocks, unless this is a tooBig event.', }, since: { type: 'string', - description: 'The rev of the last emitted commit from this repo.', + description: + 'The rev of the last emitted commit from this repo (if any).', }, blocks: { type: 'bytes', - description: 'CAR file containing relevant blocks.', + description: + 'CAR file containing relevant blocks, as a diff since the previous repo state.', maxLength: 1000000, }, ops: { @@ -4181,6 +4331,8 @@ export const schemaDict = { items: { type: 'ref', ref: 'lex:com.atproto.sync.subscribeRepos#repoOp', + description: + 'List of repo mutation operations in this commit (eg, records created, updated, or deleted).', }, maxLength: 200, }, @@ -4188,16 +4340,22 @@ export const schemaDict = { type: 'array', items: { type: 'cid-link', + description: + 'List of new blobs (by CID) referenced by records in this commit.', }, }, time: { type: 'string', format: 'datetime', + description: + 'Timestamp of when this message was originally broadcast.', }, }, }, handle: { type: 'object', + description: + "Represents an update of the account's handle, or transition to/from invalid state.", required: ['seq', 'did', 'handle', 'time'], properties: { seq: { @@ -4219,6 +4377,8 @@ export const schemaDict = { }, migrate: { type: 'object', + description: + 'Represents an account moving from one PDS instance to another. NOTE: not implemented; full account migration may introduce a new message instead.', required: ['seq', 'did', 'migrateTo', 'time'], nullable: ['migrateTo'], properties: { @@ -4240,6 +4400,7 @@ export const schemaDict = { }, tombstone: { type: 'object', + description: 'Indicates that an account has been deleted.', required: ['seq', 'did', 'time'], properties: { seq: { @@ -4270,8 +4431,7 @@ export const schemaDict = { }, repoOp: { type: 'object', - description: - "A repo operation, ie a write of a single record. For creates and updates, CID is the record's CID as of this operation. For deletes, it's null.", + description: 'A repo operation, ie a mutation of a single record.', required: ['action', 'path', 'cid'], nullable: ['cid'], properties: { @@ -4284,6 +4444,8 @@ export const schemaDict = { }, cid: { type: 'cid-link', + description: + 'For creates and updates, the new record CID. For deletions, null.', }, }, }, @@ -4324,7 +4486,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Fetch all labels from a labeler created after a certain date.', + 'Fetch all labels from a labeler created after a certain date. DEPRECATED: use queryLabels or subscribeLabels instead', parameters: { type: 'params', properties: { @@ -4440,7 +4602,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Transfer an account.', + description: + 'Transfer an account. NOTE: temporary method, necessarily how account migration will be implemented.', input: { encoding: 'application/json', schema: { @@ -4513,7 +4676,6 @@ export const schemaDict = { AppBskyActorDefs: { lexicon: 1, id: 'app.bsky.actor.defs', - description: 'A reference to an actor in the network.', defs: { profileViewBasic: { type: 'object', @@ -4646,6 +4808,8 @@ export const schemaDict = { }, 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', @@ -4731,6 +4895,9 @@ export const schemaDict = { format: 'at-uri', }, }, + timelineIndex: { + type: 'integer', + }, }, }, personalDetailsPref: { @@ -4815,7 +4982,8 @@ export const schemaDict = { 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: {}, @@ -4842,7 +5010,8 @@ export const schemaDict = { 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'], @@ -4850,6 +5019,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Handle or DID of account to fetch profile of.', }, }, }, @@ -4909,7 +5079,8 @@ export const schemaDict = { 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: { @@ -4952,7 +5123,7 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a profile.', + description: 'A declaration of a Bluesky account profile.', key: 'literal:self', record: { type: 'object', @@ -4964,21 +5135,28 @@ export const schemaDict = { }, 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: ['lex:com.atproto.label.defs#selfLabels'], }, }, @@ -5015,7 +5193,8 @@ export const schemaDict = { 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: { @@ -5067,7 +5246,8 @@ export const schemaDict = { 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: { @@ -5109,11 +5289,11 @@ export const schemaDict = { AppBskyEmbedExternal: { 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: { @@ -5177,7 +5357,7 @@ export const schemaDict = { AppBskyEmbedImages: { 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', @@ -5204,6 +5384,8 @@ export const schemaDict = { }, alt: { type: 'string', + description: + 'Alt text description of the image, for accessibility.', }, aspectRatio: { type: 'ref', @@ -5247,12 +5429,18 @@ export const schemaDict = { properties: { 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', @@ -5266,7 +5454,7 @@ export const schemaDict = { lexicon: 1, id: 'app.bsky.embed.record', description: - 'A representation of a record embedded in another form of content.', + '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', @@ -5312,6 +5500,7 @@ export const schemaDict = { }, value: { type: 'unknown', + description: 'The record data itself.', }, labels: { type: 'array', @@ -5376,7 +5565,7 @@ export const schemaDict = { lexicon: 1, id: 'app.bsky.embed.recordWithMedia', description: - 'A representation of a record embedded in another form of content, alongside other compatible embeds.', + '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', @@ -5475,6 +5664,8 @@ export const schemaDict = { }, 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', @@ -5735,7 +5926,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Get information about a feed generator, including policies and offered feed URIs.', + '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: { @@ -5790,7 +5981,8 @@ export const schemaDict = { 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', @@ -5824,6 +6016,7 @@ export const schemaDict = { }, labels: { type: 'union', + description: 'Self-label values', refs: ['lex:com.atproto.label.defs#selfLabels'], }, createdAt: { @@ -5841,7 +6034,8 @@ export const schemaDict = { 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'], @@ -5889,7 +6083,8 @@ export const schemaDict = { 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'], @@ -5945,7 +6140,8 @@ export const schemaDict = { 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'], @@ -5965,6 +6161,8 @@ export const schemaDict = { }, filter: { type: 'string', + description: + 'Combinations of post/repost types to include in response.', knownValues: [ 'posts_with_replies', 'posts_no_replies', @@ -6012,7 +6210,7 @@ export const schemaDict = { main: { type: 'query', description: - "Get a hydrated feed from an actor's selected feed generator.", + "Get a hydrated feed from an actor's selected feed generator. Implemented by App View.", parameters: { type: 'params', required: ['feed'], @@ -6065,7 +6263,8 @@ export const schemaDict = { 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'], @@ -6073,6 +6272,7 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: 'AT-URI of the feed generator record.', }, }, }, @@ -6088,9 +6288,13 @@ export const schemaDict = { }, 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.', }, }, }, @@ -6143,7 +6347,8 @@ export const schemaDict = { 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'], @@ -6151,6 +6356,8 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: + 'Reference to feed generator record describing the specific feed being requested.', }, limit: { type: 'integer', @@ -6196,7 +6403,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get the list of likes.', + description: + 'Get like records which reference a subject (by AT-URI and CID).', parameters: { type: 'params', required: ['uri'], @@ -6204,10 +6412,13 @@ export const schemaDict = { uri: { type: 'string', format: 'at-uri', + description: 'AT-URI of the subject (eg, a post record).', }, cid: { type: 'string', format: 'cid', + description: + 'CID of the subject record (aka, specific version of record), to filter likes.', }, limit: { type: 'integer', @@ -6274,7 +6485,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a view of a recent posts from actors in a list.', + description: + 'Get a feed of recent posts from a list (posts and reposts from any actors on the list). Does not require auth.', parameters: { type: 'params', required: ['list'], @@ -6282,6 +6494,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the list record.', }, limit: { type: 'integer', @@ -6327,7 +6540,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get posts in a thread.', + description: + 'Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.', parameters: { type: 'params', required: ['uri'], @@ -6335,15 +6549,20 @@ export const schemaDict = { uri: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to post record.', }, depth: { type: 'integer', + description: + 'How many levels of reply depth should be included in response.', default: 6, minimum: 0, maximum: 1000, }, parentHeight: { type: 'integer', + description: + 'How many levels of parent (and grandparent, etc) post to include.', default: 80, minimum: 0, maximum: 1000, @@ -6381,13 +6600,15 @@ export const schemaDict = { defs: { main: { type: 'query', - description: "Get a view of an actor's feed.", + description: + "Gets post views for a specified list of posts (by AT-URI). This is sometimes referred to as 'hydrating' a 'feed skeleton'.", parameters: { type: 'params', required: ['uris'], properties: { uris: { type: 'array', + description: 'List of post AT-URIs to return hydrated views for.', items: { type: 'string', format: 'at-uri', @@ -6421,7 +6642,7 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of reposts.', + description: 'Get a list of reposts for a given post.', parameters: { type: 'params', required: ['uri'], @@ -6429,10 +6650,13 @@ export const schemaDict = { uri: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) of post record', }, cid: { type: 'string', format: 'cid', + description: + 'If supplied, filters to reposts of specific version (by CID) of the post record.', }, limit: { type: 'integer', @@ -6481,7 +6705,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of suggested feeds for the viewer.', + description: + 'Get a list of suggested feeds (feed generators) for the requesting account.', parameters: { type: 'params', properties: { @@ -6524,12 +6749,15 @@ export const schemaDict = { defs: { main: { type: 'query', - description: "Get a view of the actor's home timeline.", + description: + "Get a view of the requesting account's home timeline. This is expected to be some form of reverse-chronological feed.", parameters: { type: 'params', properties: { algorithm: { type: 'string', + description: + "Variant 'algorithm' for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism.", }, limit: { type: 'integer', @@ -6570,7 +6798,7 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a like.', + description: "Record declaring a 'like' of a piece of subject content.", key: 'tid', record: { type: 'object', @@ -6595,7 +6823,7 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a post.', + description: 'Record containing a Bluesky post.', key: 'tid', record: { type: 'object', @@ -6605,10 +6833,12 @@ export const schemaDict = { type: 'string', maxLength: 3000, maxGraphemes: 300, + description: + 'The primary post content. May be an empty string, if there are embeds.', }, entities: { type: 'array', - description: 'Deprecated: replaced by app.bsky.richtext.facet.', + description: 'DEPRECATED: replaced by app.bsky.richtext.facet.', items: { type: 'ref', ref: 'lex:app.bsky.feed.post#entity', @@ -6616,6 +6846,8 @@ export const schemaDict = { }, facets: { type: 'array', + description: + 'Annotations of text (mentions, URLs, hashtags, etc)', items: { type: 'ref', ref: 'lex:app.bsky.richtext.facet', @@ -6636,6 +6868,8 @@ export const schemaDict = { }, langs: { type: 'array', + description: + 'Indicates human language of post primary text content.', maxLength: 3, items: { type: 'string', @@ -6644,21 +6878,26 @@ export const schemaDict = { }, labels: { type: 'union', + description: + 'Self-label values for this post. Effectively content warnings.', refs: ['lex:com.atproto.label.defs#selfLabels'], }, tags: { type: 'array', + description: + 'Additional hashtags, in addition to any included in post text and facets.', maxLength: 8, items: { type: 'string', maxLength: 640, maxGraphemes: 64, }, - description: 'Additional non-inline tags describing this post.', }, createdAt: { type: 'string', format: 'datetime', + description: + 'Client-declared timestamp when this post was originally created.', }, }, }, @@ -6718,7 +6957,8 @@ export const schemaDict = { id: 'app.bsky.feed.repost', defs: { main: { - description: 'A declaration of a repost.', + description: + "Record representing a 'repost' of an existing Bluesky post.", type: 'record', key: 'tid', record: { @@ -6744,7 +6984,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Find posts matching search criteria.', + description: + 'Find posts matching search criteria, returning views of those posts.', parameters: { type: 'params', required: ['q'], @@ -6807,7 +7048,7 @@ export const schemaDict = { type: 'record', key: 'tid', description: - "Defines interaction gating rules for a thread. The rkey of the threadgate record should match the rkey of the thread's root post.", + "Record defining interaction gating rules for a thread (aka, reply controls). The record key (rkey) of the threadgate record must match the record key of the thread's root post, and that record must be in the same repository..", record: { type: 'object', required: ['post', 'createdAt'], @@ -6815,6 +7056,7 @@ export const schemaDict = { post: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the post record.', }, allow: { type: 'array', @@ -6864,7 +7106,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a block.', + description: + "Record declaring a 'block' relationship against another account. NOTE: blocks are public in Bluesky; see blog posts for details.", key: 'tid', record: { type: 'object', @@ -6873,6 +7116,7 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'DID of the account to be blocked.', }, createdAt: { type: 'string', @@ -7061,7 +7305,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a social follow.', + description: + "Record declaring a social 'follow' relationship of another account. Duplicate follows will be ignored by the AppView.", key: 'tid', record: { type: 'object', @@ -7086,7 +7331,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of who the actor is blocking.', + description: + 'Enumerates which accounts the requesting account is currently blocking. Requires auth.', parameters: { type: 'params', properties: { @@ -7129,7 +7375,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: "Get a list of an actor's followers.", + description: + 'Enumerates accounts which follow a specified account (actor).', parameters: { type: 'params', required: ['actor'], @@ -7181,7 +7428,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of who the actor follows.', + description: + 'Enumerates accounts which a specified account (actor) follows.', parameters: { type: 'params', required: ['actor'], @@ -7233,7 +7481,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of actors.', + description: + "Gets a 'view' (with additional context) of a specified list.", parameters: { type: 'params', required: ['list'], @@ -7241,6 +7490,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) of the list record to hydrate.', }, limit: { type: 'integer', @@ -7285,7 +7535,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get lists that the actor is blocking.', + description: + 'Get mod lists that the requesting account (actor) is blocking. Requires auth.', parameters: { type: 'params', properties: { @@ -7328,7 +7579,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get lists that the actor is muting.', + description: + 'Enumerates mod lists that the requesting account (actor) currently has muted. Requires auth.', parameters: { type: 'params', properties: { @@ -7371,7 +7623,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of lists that belong to an actor.', + description: + 'Enumerates the lists created by a specified account (actor).', parameters: { type: 'params', required: ['actor'], @@ -7379,6 +7632,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'The account (actor) to enumerate lists from.', }, limit: { type: 'integer', @@ -7419,7 +7673,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of who the actor mutes.', + description: + 'Enumerates accounts that the requesting account (actor) currently has muted. Requires auth.', parameters: { type: 'params', properties: { @@ -7463,7 +7718,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Enumerates public relationships between one account, and a list of other accounts', + 'Enumerates public relationships between one account, and a list of other accounts. Does not require auth.', parameters: { type: 'params', required: ['actor'], @@ -7471,9 +7726,12 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Primary account requesting relationships for.', }, others: { type: 'array', + description: + "List of 'other' accounts to be related back to the primary.", maxLength: 30, items: { type: 'string', @@ -7521,7 +7779,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get suggested follows related to a given actor.', + description: + 'Enumerates follows similar to a given account (actor). Expected use is to recommend additional accounts immediately after following one account.', parameters: { type: 'params', required: ['actor'], @@ -7557,7 +7816,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a list of actors.', + description: + 'Record representing a list of accounts (actors). Scope includes both moderation-oriented lists and curration-oriented lists.', key: 'tid', record: { type: 'object', @@ -7565,12 +7825,15 @@ export const schemaDict = { properties: { purpose: { type: 'ref', + description: + 'Defines the purpose of the list (aka, moderation-oriented or curration-oriented)', ref: 'lex:app.bsky.graph.defs#listPurpose', }, name: { type: 'string', maxLength: 64, minLength: 1, + description: 'Display name for list; can not be empty.', }, description: { type: 'string', @@ -7608,7 +7871,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A block of an entire list of actors.', + description: + 'Record representing a block relationship against an entire an entire list of accounts (actors).', key: 'tid', record: { type: 'object', @@ -7617,6 +7881,7 @@ export const schemaDict = { subject: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the mod list record.', }, createdAt: { type: 'string', @@ -7633,7 +7898,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'An item under a declared list of actors.', + description: + "Record representing an account's inclusion on a specific list. The AppView will ignore duplicate listitem records.", key: 'tid', record: { type: 'object', @@ -7642,10 +7908,13 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'The account which is included on the list.', }, list: { type: 'string', format: 'at-uri', + description: + 'Reference (AT-URI) to the list record (app.bsky.graph.list).', }, createdAt: { type: 'string', @@ -7662,7 +7931,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Mute an actor by DID or handle.', + description: + 'Creates a mute relationship for the specified account. Mutes are private in Bluesky. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7685,7 +7955,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Mute a list of actors.', + description: + 'Creates a mute relationship for the specified list of accounts. Mutes are private in Bluesky. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7708,7 +7979,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Unmute an actor by DID or handle.', + description: 'Unmutes the specified account. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7731,7 +8002,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Unmute a list of actors.', + description: 'Unmutes the specified list of accounts. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7754,7 +8025,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get the count of unread notifications.', + description: + 'Count the number of unread notifications for the requesting account. Requires auth.', parameters: { type: 'params', properties: { @@ -7785,7 +8057,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of notifications.', + description: + 'Enumerate notifications for the requesting account. Requires auth.', parameters: { type: 'params', properties: { @@ -7896,7 +8169,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Register for push notifications with a service.', + description: + 'Register to receive push notifications, via a specified service, for the requesting account. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7929,7 +8203,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Notify server that the user has seen notifications.', + description: + 'Notify server that the requesting account has seen notifications. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7952,6 +8227,7 @@ export const schemaDict = { defs: { main: { type: 'object', + description: 'Annotation of a sub-string within rich text.', required: ['index', 'features'], properties: { index: { @@ -7973,7 +8249,8 @@ export const schemaDict = { }, mention: { type: 'object', - description: 'A facet feature for actor mentions.', + description: + "Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID.", required: ['did'], properties: { did: { @@ -7984,7 +8261,8 @@ export const schemaDict = { }, link: { type: 'object', - description: 'A facet feature for links.', + description: + 'Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.', required: ['uri'], properties: { uri: { @@ -7995,7 +8273,8 @@ export const schemaDict = { }, tag: { type: 'object', - description: 'A hashtag.', + description: + "Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').", required: ['tag'], properties: { tag: { @@ -8008,7 +8287,7 @@ export const schemaDict = { byteSlice: { type: 'object', description: - 'A text segment. Start is inclusive, end is exclusive. Indices are for utf8-encoded strings.', + 'Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.', required: ['byteStart', 'byteEnd'], properties: { byteStart: { diff --git a/packages/bsky/src/lexicon/types/app/bsky/actor/defs.ts b/packages/bsky/src/lexicon/types/app/bsky/actor/defs.ts index 8cdcafcb72f..a802f70f44b 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/actor/defs.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/actor/defs.ts @@ -82,6 +82,7 @@ export function validateProfileViewDetailed(v: unknown): ValidationResult { return lexicons.validate('app.bsky.actor.defs#profileViewDetailed', v) } +/** Metadata about the requesting account's relationship with the subject account. Only has meaningful content for authed requests. */ export interface ViewerState { muted?: boolean mutedByList?: AppBskyGraphDefs.ListViewBasic @@ -154,6 +155,7 @@ export function validateContentLabelPref(v: unknown): ValidationResult { export interface SavedFeedsPref { pinned: string[] saved: string[] + timelineIndex?: number [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/app/bsky/actor/getProfile.ts b/packages/bsky/src/lexicon/types/app/bsky/actor/getProfile.ts index be58c73a233..5a7b1f25bfc 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/actor/getProfile.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/actor/getProfile.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyActorDefs from './defs' export interface QueryParams { + /** Handle or DID of account to fetch profile of. */ actor: string } diff --git a/packages/bsky/src/lexicon/types/app/bsky/actor/profile.ts b/packages/bsky/src/lexicon/types/app/bsky/actor/profile.ts index 7dbc4c1ccec..8810ce7bed9 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/actor/profile.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/actor/profile.ts @@ -9,8 +9,11 @@ import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs' export interface Record { displayName?: string + /** Free-form profile description text. */ description?: string + /** Small image to be displayed next to posts from account. AKA, 'profile picture' */ avatar?: BlobRef + /** Larger horizontal image to display behind profile view. */ banner?: BlobRef labels?: | ComAtprotoLabelDefs.SelfLabels diff --git a/packages/bsky/src/lexicon/types/app/bsky/embed/external.ts b/packages/bsky/src/lexicon/types/app/bsky/embed/external.ts index f42a6cfd95c..b137ee4b6f5 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/embed/external.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/embed/external.ts @@ -6,6 +6,7 @@ import { lexicons } from '../../../../lexicons' import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' +/** A representation of some externally linked content (eg, a URL and 'card'), embedded in a Bluesky record (eg, a post). */ export interface Main { external: External [k: string]: unknown diff --git a/packages/bsky/src/lexicon/types/app/bsky/embed/images.ts b/packages/bsky/src/lexicon/types/app/bsky/embed/images.ts index 4864fad3dea..96399867a1a 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/embed/images.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/embed/images.ts @@ -26,6 +26,7 @@ export function validateMain(v: unknown): ValidationResult { export interface Image { image: BlobRef + /** Alt text description of the image, for accessibility. */ alt: string aspectRatio?: AspectRatio [k: string]: unknown @@ -76,8 +77,11 @@ export function validateView(v: unknown): ValidationResult { } export interface ViewImage { + /** Fully-qualified URL where a thumbnail of the image can be fetched. For example, CDN location provided by the App View. */ thumb: string + /** 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. */ fullsize: string + /** Alt text description of the image, for accessibility. */ alt: string aspectRatio?: AspectRatio [k: string]: unknown diff --git a/packages/bsky/src/lexicon/types/app/bsky/embed/record.ts b/packages/bsky/src/lexicon/types/app/bsky/embed/record.ts index cea5742a45e..dbe7f13152b 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/embed/record.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/embed/record.ts @@ -57,6 +57,7 @@ export interface ViewRecord { uri: string cid: string author: AppBskyActorDefs.ProfileViewBasic + /** The record data itself. */ value: {} labels?: ComAtprotoLabelDefs.Label[] embeds?: ( diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/defs.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/defs.ts index 382d3f58ecf..261d8a622ec 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/defs.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/defs.ts @@ -45,6 +45,7 @@ export function validatePostView(v: unknown): ValidationResult { return lexicons.validate('app.bsky.feed.defs#postView', v) } +/** Metadata about the requesting account's relationship with the subject content. Only has meaningful content for authed requests. */ export interface ViewerState { repost?: string like?: string diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts index 8f8e038c71f..017c7a6a2d4 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts @@ -13,6 +13,7 @@ export interface QueryParams { actor: string limit: number cursor?: string + /** Combinations of post/repost types to include in response. */ filter: | 'posts_with_replies' | 'posts_no_replies' diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts index b65a5151d46..7ab89057a8c 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** AT-URI of the feed generator record. */ feed: string } @@ -17,7 +18,9 @@ export type InputSchema = undefined export interface OutputSchema { view: AppBskyFeedDefs.GeneratorView + /** Indicates whether the feed generator service has been online recently, or else seems to be inactive. */ isOnline: boolean + /** Indicates whether the feed generator service is compatible with the record declaration. */ isValid: boolean [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts index ab1911ecb87..ca1cef20f08 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Reference to feed generator record describing the specific feed being requested. */ feed: string limit: number cursor?: string diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/getLikes.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/getLikes.ts index c7e8c860bd6..275d99bba3d 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/getLikes.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/getLikes.ts @@ -10,7 +10,9 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyActorDefs from '../actor/defs' export interface QueryParams { + /** AT-URI of the subject (eg, a post record). */ uri: string + /** CID of the subject record (aka, specific version of record), to filter likes. */ cid?: string limit: number cursor?: string diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/getListFeed.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/getListFeed.ts index ab157788f72..84e12deaa92 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/getListFeed.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/getListFeed.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Reference (AT-URI) to the list record. */ list: string limit: number cursor?: string diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/getPostThread.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/getPostThread.ts index 9e81da0eff6..ae232fd91a2 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/getPostThread.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/getPostThread.ts @@ -10,8 +10,11 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Reference (AT-URI) to post record. */ uri: string + /** How many levels of reply depth should be included in response. */ depth: number + /** How many levels of parent (and grandparent, etc) post to include. */ parentHeight: number } diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/getPosts.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/getPosts.ts index 439e2132201..85000c74787 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/getPosts.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/getPosts.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** List of post AT-URIs to return hydrated views for. */ uris: string[] } diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/getRepostedBy.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/getRepostedBy.ts index 6dea2b753c7..40e008815d9 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/getRepostedBy.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/getRepostedBy.ts @@ -10,7 +10,9 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyActorDefs from '../actor/defs' export interface QueryParams { + /** Reference (AT-URI) of post record */ uri: string + /** If supplied, filters to reposts of specific version (by CID) of the post record. */ cid?: string limit: number cursor?: string diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/getTimeline.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/getTimeline.ts index f37def5808e..5202c9eb6e3 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/getTimeline.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/getTimeline.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Variant 'algorithm' for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism. */ algorithm?: string limit: number cursor?: string diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/post.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/post.ts index 93870b4452d..881e3d199aa 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/post.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/post.ts @@ -14,9 +14,11 @@ import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs' import * as ComAtprotoRepoStrongRef from '../../../com/atproto/repo/strongRef' export interface Record { + /** The primary post content. May be an empty string, if there are embeds. */ text: string - /** Deprecated: replaced by app.bsky.richtext.facet. */ + /** DEPRECATED: replaced by app.bsky.richtext.facet. */ entities?: Entity[] + /** Annotations of text (mentions, URLs, hashtags, etc) */ facets?: AppBskyRichtextFacet.Main[] reply?: ReplyRef embed?: @@ -25,12 +27,14 @@ export interface Record { | AppBskyEmbedRecord.Main | AppBskyEmbedRecordWithMedia.Main | { $type: string; [k: string]: unknown } + /** Indicates human language of post primary text content. */ langs?: string[] labels?: | ComAtprotoLabelDefs.SelfLabels | { $type: string; [k: string]: unknown } - /** Additional non-inline tags describing this post. */ + /** Additional hashtags, in addition to any included in post text and facets. */ tags?: string[] + /** Client-declared timestamp when this post was originally created. */ createdAt: string [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/app/bsky/feed/threadgate.ts b/packages/bsky/src/lexicon/types/app/bsky/feed/threadgate.ts index 6a190d6e98a..e14140d5609 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/feed/threadgate.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/feed/threadgate.ts @@ -7,6 +7,7 @@ import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' export interface Record { + /** Reference (AT-URI) to the post record. */ post: string allow?: ( | MentionRule diff --git a/packages/bsky/src/lexicon/types/app/bsky/graph/block.ts b/packages/bsky/src/lexicon/types/app/bsky/graph/block.ts index 947463af422..b7f19f126b7 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/graph/block.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/graph/block.ts @@ -7,6 +7,7 @@ import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' export interface Record { + /** DID of the account to be blocked. */ subject: string createdAt: string [k: string]: unknown diff --git a/packages/bsky/src/lexicon/types/app/bsky/graph/getList.ts b/packages/bsky/src/lexicon/types/app/bsky/graph/getList.ts index 6b30cd7faa9..864a81b3833 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/graph/getList.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/graph/getList.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyGraphDefs from './defs' export interface QueryParams { + /** Reference (AT-URI) of the list record to hydrate. */ list: string limit: number cursor?: string diff --git a/packages/bsky/src/lexicon/types/app/bsky/graph/getLists.ts b/packages/bsky/src/lexicon/types/app/bsky/graph/getLists.ts index 6bcb3134a47..dc0c4f18bea 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/graph/getLists.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/graph/getLists.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyGraphDefs from './defs' export interface QueryParams { + /** The account (actor) to enumerate lists from. */ actor: string limit: number cursor?: string diff --git a/packages/bsky/src/lexicon/types/app/bsky/graph/getRelationships.ts b/packages/bsky/src/lexicon/types/app/bsky/graph/getRelationships.ts index 0125414ccd4..bd6b6e765ed 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/graph/getRelationships.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/graph/getRelationships.ts @@ -10,7 +10,9 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyGraphDefs from './defs' export interface QueryParams { + /** Primary account requesting relationships for. */ actor: string + /** List of 'other' accounts to be related back to the primary. */ others?: string[] } diff --git a/packages/bsky/src/lexicon/types/app/bsky/graph/list.ts b/packages/bsky/src/lexicon/types/app/bsky/graph/list.ts index 36a7fb17a3f..91c8ccee5bb 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/graph/list.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/graph/list.ts @@ -11,6 +11,7 @@ import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs' export interface Record { purpose: AppBskyGraphDefs.ListPurpose + /** Display name for list; can not be empty. */ name: string description?: string descriptionFacets?: AppBskyRichtextFacet.Main[] diff --git a/packages/bsky/src/lexicon/types/app/bsky/graph/listblock.ts b/packages/bsky/src/lexicon/types/app/bsky/graph/listblock.ts index 59f2e057eb5..592778c7a51 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/graph/listblock.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/graph/listblock.ts @@ -7,6 +7,7 @@ import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' export interface Record { + /** Reference (AT-URI) to the mod list record. */ subject: string createdAt: string [k: string]: unknown diff --git a/packages/bsky/src/lexicon/types/app/bsky/graph/listitem.ts b/packages/bsky/src/lexicon/types/app/bsky/graph/listitem.ts index 69eff329ed4..5e93b34a111 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/graph/listitem.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/graph/listitem.ts @@ -7,7 +7,9 @@ import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' export interface Record { + /** The account which is included on the list. */ subject: string + /** Reference (AT-URI) to the list record (app.bsky.graph.list). */ list: string createdAt: string [k: string]: unknown diff --git a/packages/bsky/src/lexicon/types/app/bsky/richtext/facet.ts b/packages/bsky/src/lexicon/types/app/bsky/richtext/facet.ts index 2c5b2d723a9..139b5382caf 100644 --- a/packages/bsky/src/lexicon/types/app/bsky/richtext/facet.ts +++ b/packages/bsky/src/lexicon/types/app/bsky/richtext/facet.ts @@ -6,6 +6,7 @@ import { lexicons } from '../../../../lexicons' import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' +/** Annotation of a sub-string within rich text. */ export interface Main { index: ByteSlice features: (Mention | Link | Tag | { $type: string; [k: string]: unknown })[] @@ -25,7 +26,7 @@ export function validateMain(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#main', v) } -/** A facet feature for actor mentions. */ +/** Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID. */ export interface Mention { did: string [k: string]: unknown @@ -43,7 +44,7 @@ export function validateMention(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#mention', v) } -/** A facet feature for links. */ +/** Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL. */ export interface Link { uri: string [k: string]: unknown @@ -61,7 +62,7 @@ export function validateLink(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#link', v) } -/** A hashtag. */ +/** Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags'). */ export interface Tag { tag: string [k: string]: unknown @@ -77,7 +78,7 @@ export function validateTag(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#tag', v) } -/** A text segment. Start is inclusive, end is exclusive. Indices are for utf8-encoded strings. */ +/** Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets. */ export interface ByteSlice { byteStart: number byteEnd: number diff --git a/packages/bsky/src/lexicon/types/com/atproto/admin/defs.ts b/packages/bsky/src/lexicon/types/com/atproto/admin/defs.ts index 2fab0bc19a4..a713a635635 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/admin/defs.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/admin/defs.ts @@ -156,6 +156,7 @@ export interface SubjectStatusView { /** True indicates that the a previously taken moderator action was appealed against, by the author of the content. False indicates last appeal was resolved by moderators. */ appealed?: boolean suspendUntil?: string + tags?: string[] [k: string]: unknown } @@ -720,6 +721,29 @@ export function validateModEventEmail(v: unknown): ValidationResult { return lexicons.validate('com.atproto.admin.defs#modEventEmail', v) } +/** Add/Remove a tag on a subject */ +export interface ModEventTag { + /** Tags to be added to the subject. If already exists, won't be duplicated. */ + add: string[] + /** Tags to be removed to the subject. Ignores a tag If it doesn't exist, won't be duplicated. */ + remove: string[] + /** Additional comment about added/removed tags. */ + comment?: string + [k: string]: unknown +} + +export function isModEventTag(v: unknown): v is ModEventTag { + return ( + isObj(v) && + hasProp(v, '$type') && + v.$type === 'com.atproto.admin.defs#modEventTag' + ) +} + +export function validateModEventTag(v: unknown): ValidationResult { + return lexicons.validate('com.atproto.admin.defs#modEventTag', v) +} + export interface CommunicationTemplateView { id: string /** Name of the template. */ diff --git a/packages/bsky/src/lexicon/types/com/atproto/admin/emitModerationEvent.ts b/packages/bsky/src/lexicon/types/com/atproto/admin/emitModerationEvent.ts index 3c0acabd0eb..99d08c7f1b7 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/admin/emitModerationEvent.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/admin/emitModerationEvent.ts @@ -24,6 +24,7 @@ export interface InputSchema { | ComAtprotoAdminDefs.ModEventReverseTakedown | ComAtprotoAdminDefs.ModEventUnmute | ComAtprotoAdminDefs.ModEventEmail + | ComAtprotoAdminDefs.ModEventTag | { $type: string; [k: string]: unknown } subject: | ComAtprotoAdminDefs.RepoRef diff --git a/packages/bsky/src/lexicon/types/com/atproto/admin/queryModerationEvents.ts b/packages/bsky/src/lexicon/types/com/atproto/admin/queryModerationEvents.ts index df07cfaf2da..9f4738578aa 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/admin/queryModerationEvents.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/admin/queryModerationEvents.ts @@ -31,6 +31,10 @@ export interface QueryParams { addedLabels?: string[] /** If specified, only events where all of these labels were removed are returned */ removedLabels?: string[] + /** If specified, only events where all of these tags were added are returned */ + addedTags?: string[] + /** If specified, only events where all of these tags were removed are returned */ + removedTags?: string[] reportTypes?: string[] cursor?: string } diff --git a/packages/bsky/src/lexicon/types/com/atproto/admin/queryModerationStatuses.ts b/packages/bsky/src/lexicon/types/com/atproto/admin/queryModerationStatuses.ts index 0cc21c25352..f5031d25117 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/admin/queryModerationStatuses.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/admin/queryModerationStatuses.ts @@ -35,6 +35,8 @@ export interface QueryParams { /** Get subjects in unresolved appealed status */ appealed?: boolean limit: number + tags?: string[] + excludeTags?: string[] cursor?: string } diff --git a/packages/bsky/src/lexicon/types/com/atproto/identity/updateHandle.ts b/packages/bsky/src/lexicon/types/com/atproto/identity/updateHandle.ts index 6782a68ed54..f451d1f57c7 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/identity/updateHandle.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/identity/updateHandle.ts @@ -11,6 +11,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { + /** The new handle. */ handle: string [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/com/atproto/label/subscribeLabels.ts b/packages/bsky/src/lexicon/types/com/atproto/label/subscribeLabels.ts index 9d4b4441ae0..6034b35d895 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/label/subscribeLabels.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/label/subscribeLabels.ts @@ -10,7 +10,7 @@ import { IncomingMessage } from 'http' import * as ComAtprotoLabelDefs from './defs' export interface QueryParams { - /** The last known event to backfill from. */ + /** The last known event seq number to backfill from. */ cursor?: number } diff --git a/packages/bsky/src/lexicon/types/com/atproto/moderation/createReport.ts b/packages/bsky/src/lexicon/types/com/atproto/moderation/createReport.ts index c1335eb3d1f..aa3f810a91c 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/moderation/createReport.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/moderation/createReport.ts @@ -15,6 +15,7 @@ export interface QueryParams {} export interface InputSchema { reasonType: ComAtprotoModerationDefs.ReasonType + /** Additional context about the content and violation. */ reason?: string subject: | ComAtprotoAdminDefs.RepoRef diff --git a/packages/bsky/src/lexicon/types/com/atproto/repo/applyWrites.ts b/packages/bsky/src/lexicon/types/com/atproto/repo/applyWrites.ts index 7bdb6dc2ed1..3956d7c3048 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/repo/applyWrites.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/repo/applyWrites.ts @@ -11,11 +11,12 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string - /** Flag for validating the records. */ + /** Can be set to 'false' to skip Lexicon schema validation of record data, for all operations. */ validate: boolean writes: (Create | Update | Delete)[] + /** If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations. */ swapCommit?: string [k: string]: unknown } @@ -43,7 +44,7 @@ export type Handler = ( ctx: HandlerReqCtx, ) => Promise | HandlerOutput -/** Create a new record. */ +/** Operation which creates a new record. */ export interface Create { collection: string rkey?: string @@ -63,7 +64,7 @@ export function validateCreate(v: unknown): ValidationResult { return lexicons.validate('com.atproto.repo.applyWrites#create', v) } -/** Update an existing record. */ +/** Operation which updates an existing record. */ export interface Update { collection: string rkey: string @@ -83,7 +84,7 @@ export function validateUpdate(v: unknown): ValidationResult { return lexicons.validate('com.atproto.repo.applyWrites#update', v) } -/** Delete an existing record. */ +/** Operation which deletes an existing record. */ export interface Delete { collection: string rkey: string diff --git a/packages/bsky/src/lexicon/types/com/atproto/repo/createRecord.ts b/packages/bsky/src/lexicon/types/com/atproto/repo/createRecord.ts index 666b91c828d..55cc95d0ad7 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/repo/createRecord.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/repo/createRecord.ts @@ -11,15 +11,15 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey?: string - /** Flag for validating the record. */ + /** Can be set to 'false' to skip Lexicon schema validation of record data. */ validate: boolean - /** The record to create. */ + /** The record itself. Must contain a $type field. */ record: {} /** Compare and swap with the previous commit by CID. */ swapCommit?: string diff --git a/packages/bsky/src/lexicon/types/com/atproto/repo/deleteRecord.ts b/packages/bsky/src/lexicon/types/com/atproto/repo/deleteRecord.ts index 65ee32d213d..3bb97be0aad 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/repo/deleteRecord.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/repo/deleteRecord.ts @@ -11,11 +11,11 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey: string /** Compare and swap with the previous record by CID. */ swapRecord?: string diff --git a/packages/bsky/src/lexicon/types/com/atproto/repo/describeRepo.ts b/packages/bsky/src/lexicon/types/com/atproto/repo/describeRepo.ts index 38b9c01ef1c..749bedcfeb7 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/repo/describeRepo.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/repo/describeRepo.ts @@ -18,8 +18,11 @@ export type InputSchema = undefined export interface OutputSchema { handle: string did: string + /** The complete DID document for this account. */ didDoc: {} + /** List of all the collections (NSIDs) for which this repo contains at least one record. */ collections: string[] + /** Indicates if handle is currently valid (resolves bi-directionally) */ handleIsCorrect: boolean [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/com/atproto/repo/getRecord.ts b/packages/bsky/src/lexicon/types/com/atproto/repo/getRecord.ts index 345dde29a53..1a737a848be 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/repo/getRecord.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/repo/getRecord.ts @@ -13,7 +13,7 @@ export interface QueryParams { repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey: string /** The CID of the version of the record. If not specified, then return the most recent version. */ cid?: string diff --git a/packages/bsky/src/lexicon/types/com/atproto/repo/putRecord.ts b/packages/bsky/src/lexicon/types/com/atproto/repo/putRecord.ts index de93e2e9cf7..193841a2294 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/repo/putRecord.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/repo/putRecord.ts @@ -11,17 +11,17 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey: string - /** Flag for validating the record. */ + /** Can be set to 'false' to skip Lexicon schema validation of record data. */ validate: boolean /** The record to write. */ record: {} - /** Compare and swap with the previous record by CID. */ + /** Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation */ swapRecord?: string | null /** Compare and swap with the previous commit by CID. */ swapCommit?: string diff --git a/packages/bsky/src/lexicon/types/com/atproto/server/createAccount.ts b/packages/bsky/src/lexicon/types/com/atproto/server/createAccount.ts index bceb61546cf..6e9b2f9f3c2 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/server/createAccount.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/server/createAccount.ts @@ -12,22 +12,30 @@ export interface QueryParams {} export interface InputSchema { email?: string + /** Requested handle for the account. */ handle: string + /** Pre-existing atproto DID, being imported to a new account. */ did?: string inviteCode?: string verificationCode?: string verificationPhone?: string + /** Initial account password. May need to meet instance-specific password strength requirements. */ password?: string + /** DID PLC rotation key (aka, recovery key) to be included in PLC creation operation. */ recoveryKey?: string + /** A signed DID PLC operation to be submitted as part of importing an existing account to this instance. NOTE: this optional field may be updated when full account migration is implemented. */ plcOp?: {} [k: string]: unknown } +/** Account login session returned on successful account creation. */ export interface OutputSchema { accessJwt: string refreshJwt: string handle: string + /** The DID of the new account. */ did: string + /** Complete DID document. */ didDoc?: {} [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/com/atproto/server/createAppPassword.ts b/packages/bsky/src/lexicon/types/com/atproto/server/createAppPassword.ts index 474846546fe..dcc5178ecfa 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/server/createAppPassword.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/server/createAppPassword.ts @@ -11,6 +11,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { + /** A short name for the App Password, to help distinguish them. */ name: string [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/com/atproto/server/describeServer.ts b/packages/bsky/src/lexicon/types/com/atproto/server/describeServer.ts index 47be5b598b0..0e64c9d9708 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/server/describeServer.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/server/describeServer.ts @@ -13,8 +13,11 @@ export interface QueryParams {} export type InputSchema = undefined export interface OutputSchema { + /** If true, an invite code must be supplied to create an account on this instance. */ inviteCodeRequired?: boolean + /** If true, a phone verification token must be supplied to create an account on this instance. */ phoneVerificationRequired?: boolean + /** List of domain suffixes that can be used in account handles. */ availableUserDomains: string[] links?: Links [k: string]: unknown diff --git a/packages/bsky/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts b/packages/bsky/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts index 2dc551a477c..82c3ffa8c31 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts @@ -11,6 +11,7 @@ import * as ComAtprotoServerDefs from './defs' export interface QueryParams { includeUsed: boolean + /** Controls whether any new 'earned' but not 'created' invites should be created. */ createAvailable: boolean } diff --git a/packages/bsky/src/lexicon/types/com/atproto/server/reserveSigningKey.ts b/packages/bsky/src/lexicon/types/com/atproto/server/reserveSigningKey.ts index 0de1220f4b5..0ec1e80c77c 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/server/reserveSigningKey.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/server/reserveSigningKey.ts @@ -11,13 +11,13 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The did to reserve a new did:key for */ + /** The DID to reserve a key for. */ did?: string [k: string]: unknown } export interface OutputSchema { - /** Public signing key in the form of a did:key. */ + /** The public key for the reserved signing key, in did:key serialization. */ signingKey: string [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/com/atproto/sync/getBlob.ts b/packages/bsky/src/lexicon/types/com/atproto/sync/getBlob.ts index b3980fca500..93e50403f20 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/sync/getBlob.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/sync/getBlob.ts @@ -10,7 +10,7 @@ import { CID } from 'multiformats/cid' import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams { - /** The DID of the repo. */ + /** The DID of the account. */ did: string /** The CID of the blob to fetch */ cid: string diff --git a/packages/bsky/src/lexicon/types/com/atproto/sync/getRecord.ts b/packages/bsky/src/lexicon/types/com/atproto/sync/getRecord.ts index e27878ff5e6..c78ff8c2089 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/sync/getRecord.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/sync/getRecord.ts @@ -13,6 +13,7 @@ export interface QueryParams { /** The DID of the repo. */ did: string collection: string + /** Record Key */ rkey: string /** An optional past commit CID. */ commit?: string diff --git a/packages/bsky/src/lexicon/types/com/atproto/sync/getRepo.ts b/packages/bsky/src/lexicon/types/com/atproto/sync/getRepo.ts index e0ad53ded7c..0d426557c5f 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/sync/getRepo.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/sync/getRepo.ts @@ -12,7 +12,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams { /** The DID of the repo. */ did: string - /** The revision of the repo to catch up from. */ + /** The revision ('rev') of the repo to create a diff from. */ since?: string } diff --git a/packages/bsky/src/lexicon/types/com/atproto/sync/listRepos.ts b/packages/bsky/src/lexicon/types/com/atproto/sync/listRepos.ts index 12532860895..e5a8e2ca9d6 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/sync/listRepos.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/sync/listRepos.ts @@ -48,6 +48,7 @@ export type Handler = ( export interface Repo { did: string + /** Current repo commit CID */ head: string rev: string [k: string]: unknown diff --git a/packages/bsky/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts b/packages/bsky/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts index f9498e6691d..8a0af577c7c 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts @@ -11,7 +11,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** Hostname of the service that is notifying of update. */ + /** Hostname of the current service (usually a PDS) that is notifying of update. */ hostname: string [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/com/atproto/sync/requestCrawl.ts b/packages/bsky/src/lexicon/types/com/atproto/sync/requestCrawl.ts index 2859e28fe69..31180aabf58 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/sync/requestCrawl.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/sync/requestCrawl.ts @@ -11,7 +11,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** Hostname of the service that is requesting to be crawled. */ + /** Hostname of the current service (eg, PDS) that is requesting to be crawled. */ hostname: string [k: string]: unknown } diff --git a/packages/bsky/src/lexicon/types/com/atproto/sync/subscribeRepos.ts b/packages/bsky/src/lexicon/types/com/atproto/sync/subscribeRepos.ts index fb334778bf6..689ea76daee 100644 --- a/packages/bsky/src/lexicon/types/com/atproto/sync/subscribeRepos.ts +++ b/packages/bsky/src/lexicon/types/com/atproto/sync/subscribeRepos.ts @@ -9,7 +9,7 @@ import { HandlerAuth, ErrorFrame } from '@atproto/xrpc-server' import { IncomingMessage } from 'http' export interface QueryParams { - /** The last known event to backfill from. */ + /** The last known event seq number to backfill from. */ cursor?: number } @@ -32,21 +32,29 @@ export type Handler = ( ctx: HandlerReqCtx, ) => AsyncIterable +/** Represents an update of repository state. Note that empty commits are allowed, which include no repo data changes, but an update to rev and signature. */ export interface Commit { + /** The stream sequence number of this message. */ seq: number + /** DEPRECATED -- unused */ rebase: boolean + /** Indicates that this commit contained too many ops, or data size was too large. Consumers will need to make a separate request to get missing data. */ tooBig: boolean + /** The repo this event comes from. */ repo: string + /** Repo commit object CID. */ commit: CID + /** DEPRECATED -- unused. WARNING -- nullable and optional; stick with optional to ensure golang interoperability. */ prev?: CID | null - /** The rev of the emitted commit. */ + /** The rev of the emitted commit. Note that this information is also in the commit object included in blocks, unless this is a tooBig event. */ rev: string - /** The rev of the last emitted commit from this repo. */ + /** The rev of the last emitted commit from this repo (if any). */ since: string | null - /** CAR file containing relevant blocks. */ + /** CAR file containing relevant blocks, as a diff since the previous repo state. */ blocks: Uint8Array ops: RepoOp[] blobs: CID[] + /** Timestamp of when this message was originally broadcast. */ time: string [k: string]: unknown } @@ -63,6 +71,7 @@ export function validateCommit(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#commit', v) } +/** Represents an update of the account's handle, or transition to/from invalid state. */ export interface Handle { seq: number did: string @@ -83,6 +92,7 @@ export function validateHandle(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#handle', v) } +/** Represents an account moving from one PDS instance to another. NOTE: not implemented; full account migration may introduce a new message instead. */ export interface Migrate { seq: number did: string @@ -103,6 +113,7 @@ export function validateMigrate(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#migrate', v) } +/** Indicates that an account has been deleted. */ export interface Tombstone { seq: number did: string @@ -140,10 +151,11 @@ export function validateInfo(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#info', v) } -/** A repo operation, ie a write of a single record. For creates and updates, CID is the record's CID as of this operation. For deletes, it's null. */ +/** A repo operation, ie a mutation of a single record. */ export interface RepoOp { action: 'create' | 'update' | 'delete' | (string & {}) path: string + /** For creates and updates, the new record CID. For deletions, null. */ cid: CID | null [k: string]: unknown } diff --git a/packages/pds/src/lexicon/lexicons.ts b/packages/pds/src/lexicon/lexicons.ts index 9db3be4f817..f3490b79dfd 100644 --- a/packages/pds/src/lexicon/lexicons.ts +++ b/packages/pds/src/lexicon/lexicons.ts @@ -303,6 +303,12 @@ export const schemaDict = { type: 'string', format: 'datetime', }, + tags: { + type: 'array', + items: { + type: 'string', + }, + }, }, }, reportViewDetail: { @@ -897,6 +903,33 @@ export const schemaDict = { }, }, }, + modEventTag: { + type: 'object', + description: 'Add/Remove a tag on a subject', + required: ['add', 'remove'], + properties: { + add: { + type: 'array', + items: { + type: 'string', + }, + description: + "Tags to be added to the subject. If already exists, won't be duplicated.", + }, + remove: { + type: 'array', + items: { + type: 'string', + }, + description: + "Tags to be removed to the subject. Ignores a tag If it doesn't exist, won't be duplicated.", + }, + comment: { + type: 'string', + description: 'Additional comment about added/removed tags.', + }, + }, + }, communicationTemplateView: { type: 'object', required: [ @@ -1075,6 +1108,7 @@ export const schemaDict = { 'lex:com.atproto.admin.defs#modEventReverseTakedown', 'lex:com.atproto.admin.defs#modEventUnmute', 'lex:com.atproto.admin.defs#modEventEmail', + 'lex:com.atproto.admin.defs#modEventTag', ], }, subject: { @@ -1503,6 +1537,22 @@ export const schemaDict = { description: 'If specified, only events where all of these labels were removed are returned', }, + addedTags: { + type: 'array', + items: { + type: 'string', + }, + description: + 'If specified, only events where all of these tags were added are returned', + }, + removedTags: { + type: 'array', + items: { + type: 'string', + }, + description: + 'If specified, only events where all of these tags were removed are returned', + }, reportTypes: { type: 'array', items: { @@ -1620,6 +1670,18 @@ export const schemaDict = { maximum: 100, default: 50, }, + tags: { + type: 'array', + items: { + type: 'string', + }, + }, + excludeTags: { + type: 'array', + items: { + type: 'string', + }, + }, cursor: { type: 'string', }, @@ -1912,7 +1974,7 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Provides the DID of a repo.', + description: 'Resolves a handle (domain name) to a DID.', parameters: { type: 'params', required: ['handle'], @@ -1946,7 +2008,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Updates the handle of the account.', + description: + "Updates the current account's handle. Verifies handle validity, and updates did:plc document if necessary. Implemented by PDS, and requires auth.", input: { encoding: 'application/json', schema: { @@ -1956,6 +2019,7 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'The new handle.', }, }, }, @@ -2046,7 +2110,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Find labels relevant to the provided URI patterns.', + description: + 'Find labels relevant to the provided AT-URI patterns. Public endpoint for moderation services, though may return different or additional results with auth.', parameters: { type: 'params', required: ['uriPatterns'], @@ -2107,13 +2172,14 @@ export const schemaDict = { defs: { main: { type: 'subscription', - description: 'Subscribe to label updates.', + description: + 'Subscribe to stream of labels (and negations). Public endpoint implemented by mod services. Uses same sequencing scheme as repo event stream.', parameters: { type: 'params', properties: { cursor: { type: 'integer', - description: 'The last known event to backfill from.', + description: 'The last known event seq number to backfill from.', }, }, }, @@ -2169,7 +2235,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Report a repo or a record.', + description: + 'Submit a moderation report regarding an atproto account or record. Implemented by moderation services (with PDS proxying), and requires auth.', input: { encoding: 'application/json', schema: { @@ -2178,10 +2245,14 @@ export const schemaDict = { properties: { reasonType: { type: 'ref', + description: + 'Indicates the broad category of violation the report is for.', ref: 'lex:com.atproto.moderation.defs#reasonType', }, reason: { type: 'string', + description: + 'Additional context about the content and violation.', }, subject: { type: 'union', @@ -2292,7 +2363,7 @@ export const schemaDict = { main: { type: 'procedure', description: - 'Apply a batch transaction of creates, updates, and deletes.', + 'Apply a batch transaction of repository creates, updates, and deletes. Requires auth, implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2302,12 +2373,14 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, validate: { type: 'boolean', default: true, - description: 'Flag for validating the records.', + description: + "Can be set to 'false' to skip Lexicon schema validation of record data, for all operations.", }, writes: { type: 'array', @@ -2323,6 +2396,8 @@ export const schemaDict = { }, swapCommit: { type: 'string', + description: + 'If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations.', format: 'cid', }, }, @@ -2331,12 +2406,14 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that the 'swapCommit' parameter did not match current commit.", }, ], }, create: { type: 'object', - description: 'Create a new record.', + description: 'Operation which creates a new record.', required: ['collection', 'value'], properties: { collection: { @@ -2354,7 +2431,7 @@ export const schemaDict = { }, update: { type: 'object', - description: 'Update an existing record.', + description: 'Operation which updates an existing record.', required: ['collection', 'rkey', 'value'], properties: { collection: { @@ -2371,7 +2448,7 @@ export const schemaDict = { }, delete: { type: 'object', - description: 'Delete an existing record.', + description: 'Operation which deletes an existing record.', required: ['collection', 'rkey'], properties: { collection: { @@ -2391,7 +2468,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Create a new record.', + description: + 'Create a single new repository record. Requires auth, implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2401,7 +2479,8 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, collection: { type: 'string', @@ -2410,17 +2489,18 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', maxLength: 15, }, validate: { type: 'boolean', default: true, - description: 'Flag for validating the record.', + description: + "Can be set to 'false' to skip Lexicon schema validation of record data.", }, record: { type: 'unknown', - description: 'The record to create.', + description: 'The record itself. Must contain a $type field.', }, swapCommit: { type: 'string', @@ -2451,6 +2531,8 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that 'swapCommit' didn't match current repo commit.", }, ], }, @@ -2462,7 +2544,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: "Delete a record, or ensure it doesn't exist.", + description: + "Delete a repository record, or ensure it doesn't exist. Requires auth, implemented by PDS.", input: { encoding: 'application/json', schema: { @@ -2472,7 +2555,8 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, collection: { type: 'string', @@ -2481,7 +2565,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, swapRecord: { type: 'string', @@ -2513,7 +2597,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Get information about the repo, including the list of collections.', + 'Get information about an account and repository, including the list of collections. Does not require auth.', parameters: { type: 'params', required: ['repo'], @@ -2547,9 +2631,12 @@ export const schemaDict = { }, didDoc: { type: 'unknown', + description: 'The complete DID document for this account.', }, collections: { type: 'array', + description: + 'List of all the collections (NSIDs) for which this repo contains at least one record.', items: { type: 'string', format: 'nsid', @@ -2557,6 +2644,8 @@ export const schemaDict = { }, handleIsCorrect: { type: 'boolean', + description: + 'Indicates if handle is currently valid (resolves bi-directionally)', }, }, }, @@ -2570,7 +2659,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a record.', + description: + 'Get a single record from a repository. Does not require auth.', parameters: { type: 'params', required: ['repo', 'collection', 'rkey'], @@ -2587,7 +2677,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, cid: { type: 'string', @@ -2626,7 +2716,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'List a range of records in a collection.', + description: + 'List a range of records in a repository, matching a specific collection. Does not require auth.', parameters: { type: 'params', required: ['repo', 'collection'], @@ -2712,7 +2803,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Write a record, creating or updating it as needed.', + description: + 'Write a repository record, creating or updating it as needed. Requires auth, implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2723,7 +2815,8 @@ export const schemaDict = { repo: { type: 'string', format: 'at-identifier', - description: 'The handle or DID of the repo.', + description: + 'The handle or DID of the repo (aka, current account).', }, collection: { type: 'string', @@ -2732,13 +2825,14 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', maxLength: 15, }, validate: { type: 'boolean', default: true, - description: 'Flag for validating the record.', + description: + "Can be set to 'false' to skip Lexicon schema validation of record data.", }, record: { type: 'unknown', @@ -2748,7 +2842,7 @@ export const schemaDict = { type: 'string', format: 'cid', description: - 'Compare and swap with the previous record by CID.', + 'Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation', }, swapCommit: { type: 'string', @@ -2812,7 +2906,7 @@ export const schemaDict = { main: { type: 'procedure', description: - 'Upload a new blob to be added to repo in a later request.', + 'Upload a new blob, to be referenced from a repository record. The blob will be deleted if it is not referenced within a time window (eg, minutes). Blob restrictions (mimetype, size, etc) are enforced when the reference is created. Requires auth, implemented by PDS.', input: { encoding: '*/*', }, @@ -2877,7 +2971,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Create an account.', + description: 'Create an account. Implemented by PDS.', input: { encoding: 'application/json', schema: { @@ -2890,10 +2984,13 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'Requested handle for the account.', }, did: { type: 'string', format: 'did', + description: + 'Pre-existing atproto DID, being imported to a new account.', }, inviteCode: { type: 'string', @@ -2906,12 +3003,18 @@ export const schemaDict = { }, password: { type: 'string', + description: + 'Initial account password. May need to meet instance-specific password strength requirements.', }, recoveryKey: { type: 'string', + description: + 'DID PLC rotation key (aka, recovery key) to be included in PLC creation operation.', }, plcOp: { type: 'unknown', + description: + 'A signed DID PLC operation to be submitted as part of importing an existing account to this instance. NOTE: this optional field may be updated when full account migration is implemented.', }, }, }, @@ -2920,6 +3023,8 @@ export const schemaDict = { encoding: 'application/json', schema: { type: 'object', + description: + 'Account login session returned on successful account creation.', required: ['accessJwt', 'refreshJwt', 'handle', 'did'], properties: { accessJwt: { @@ -2935,9 +3040,11 @@ export const schemaDict = { did: { type: 'string', format: 'did', + description: 'The DID of the new account.', }, didDoc: { type: 'unknown', + description: 'Complete DID document.', }, }, }, @@ -2983,6 +3090,8 @@ export const schemaDict = { properties: { name: { type: 'string', + description: + 'A short name for the App Password, to help distinguish them.', }, }, }, @@ -3250,7 +3359,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: "Delete an actor's account with a token and password.", + description: + "Delete an actor's account with a token and password. Can only be called after requesting a deletion token. Requires auth.", input: { encoding: 'application/json', schema: { @@ -3287,7 +3397,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Delete the current session.', + description: 'Delete the current session. Requires auth.', }, }, }, @@ -3298,7 +3408,7 @@ export const schemaDict = { main: { type: 'query', description: - "Get a document describing the service's accounts configuration.", + "Describes the server's account creation requirements and capabilities. Implemented by PDS.", output: { encoding: 'application/json', schema: { @@ -3307,18 +3417,25 @@ export const schemaDict = { properties: { inviteCodeRequired: { type: 'boolean', + description: + 'If true, an invite code must be supplied to create an account on this instance.', }, phoneVerificationRequired: { type: 'boolean', + description: + 'If true, a phone verification token must be supplied to create an account on this instance.', }, availableUserDomains: { type: 'array', + description: + 'List of domain suffixes that can be used in account handles.', items: { type: 'string', }, }, links: { type: 'ref', + description: 'URLs of service policy documents.', ref: 'lex:com.atproto.server.describeServer#links', }, }, @@ -3344,7 +3461,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get all invite codes for a given account.', + description: + 'Get all invite codes for the current account. Requires auth.', parameters: { type: 'params', properties: { @@ -3355,6 +3473,8 @@ export const schemaDict = { createAvailable: { type: 'boolean', default: true, + description: + "Controls whether any new 'earned' but not 'created' invites should be created.", }, }, }, @@ -3388,7 +3508,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get information about the current session.', + description: + 'Get information about the current auth session. Requires auth.', output: { encoding: 'application/json', schema: { @@ -3468,7 +3589,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Refresh an authentication session.', + description: + "Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt').", output: { encoding: 'application/json', schema: { @@ -3574,7 +3696,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Reserve a repo signing key for account creation.', + description: + 'Reserve a repo signing key, for use with account creation. Necessary so that a DID PLC update operation can be constructed during an account migraiton. Public and does not require auth; implemented by PDS. NOTE: this endpoint may change when full account migration is implemented.', input: { encoding: 'application/json', schema: { @@ -3582,7 +3705,8 @@ export const schemaDict = { properties: { did: { type: 'string', - description: 'The did to reserve a new did:key for', + format: 'did', + description: 'The DID to reserve a key for.', }, }, }, @@ -3595,7 +3719,8 @@ export const schemaDict = { properties: { signingKey: { type: 'string', - description: 'Public signing key in the form of a did:key.', + description: + 'The public key for the reserved signing key, in did:key serialization.', }, }, }, @@ -3702,7 +3827,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a blob associated with a given repo.', + description: + 'Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS.', parameters: { type: 'params', required: ['did', 'cid'], @@ -3710,7 +3836,7 @@ export const schemaDict = { did: { type: 'string', format: 'did', - description: 'The DID of the repo.', + description: 'The DID of the account.', }, cid: { type: 'string', @@ -3731,7 +3857,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get blocks from a given repo.', + description: + 'Get data blocks from a given repo, by CID. For example, intermediate MST nodes, or records. Does not require auth; implemented by PDS.', parameters: { type: 'params', required: ['did', 'cids'], @@ -3826,7 +3953,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get the current commit CID & revision of the repo.', + description: + 'Get the current commit CID & revision of the specified repo. Does not require auth.', parameters: { type: 'params', required: ['did'], @@ -3869,7 +3997,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Get blocks needed for existence or non-existence of record.', + 'Get data blocks needed to prove the existence or non-existence of record in the current version of repo. Does not require auth.', parameters: { type: 'params', required: ['did', 'collection', 'rkey'], @@ -3885,6 +4013,7 @@ export const schemaDict = { }, rkey: { type: 'string', + description: 'Record Key', }, commit: { type: 'string', @@ -3906,7 +4035,7 @@ export const schemaDict = { main: { type: 'query', description: - "Gets the DID's repo, optionally catching up from a specific revision.", + "Download a repository export as CAR file. Optionally only a 'diff' since a previous revision. Does not require auth; implemented by PDS.", parameters: { type: 'params', required: ['did'], @@ -3918,7 +4047,8 @@ export const schemaDict = { }, since: { type: 'string', - description: 'The revision of the repo to catch up from.', + description: + "The revision ('rev') of the repo to create a diff from.", }, }, }, @@ -3934,7 +4064,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'List blob CIDs since some revision.', + description: + 'List blob CIDso for an account, since some repo revision. Does not require auth; implemented by PDS.', parameters: { type: 'params', required: ['did'], @@ -3987,7 +4118,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'List DIDs and root CIDs of hosted repos.', + description: + 'Enumerates all the DID, rev, and commit CID for all repos hosted by this service. Does not require auth; implemented by PDS and Relay.', parameters: { type: 'params', properties: { @@ -4033,6 +4165,7 @@ export const schemaDict = { head: { type: 'string', format: 'cid', + description: 'Current repo commit CID', }, rev: { type: 'string', @@ -4048,7 +4181,7 @@ export const schemaDict = { main: { type: 'procedure', description: - 'Notify a crawling service of a recent update; often when a long break between updates causes the connection with the crawling service to break.', + 'Notify a crawling service of a recent update, and that crawling should resume. Intended use is after a gap between repo stream events caused the crawling service to disconnect. Does not require auth; implemented by Relay.', input: { encoding: 'application/json', schema: { @@ -4058,7 +4191,7 @@ export const schemaDict = { hostname: { type: 'string', description: - 'Hostname of the service that is notifying of update.', + 'Hostname of the current service (usually a PDS) that is notifying of update.', }, }, }, @@ -4072,7 +4205,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Request a service to persistently crawl hosted repos.', + description: + 'Request a service to persistently crawl hosted repos. Expected use is new PDS instances declaring their existence to Relays. Does not require auth.', input: { encoding: 'application/json', schema: { @@ -4082,7 +4216,7 @@ export const schemaDict = { hostname: { type: 'string', description: - 'Hostname of the service that is requesting to be crawled.', + 'Hostname of the current service (eg, PDS) that is requesting to be crawled.', }, }, }, @@ -4096,13 +4230,14 @@ export const schemaDict = { defs: { main: { type: 'subscription', - description: 'Subscribe to repo updates.', + description: + 'Repository event stream, aka Firehose endpoint. Outputs repo commits with diff data, and identity update events, for all repositories on the current server. See the atproto specifications for details around stream sequencing, repo versioning, CAR diff format, and more. Public and does not require auth; implemented by PDS and Relay.', parameters: { type: 'params', properties: { cursor: { type: 'integer', - description: 'The last known event to backfill from.', + description: 'The last known event seq number to backfill from.', }, }, }, @@ -4124,11 +4259,15 @@ export const schemaDict = { }, { name: 'ConsumerTooSlow', + description: + 'If the consumer of the stream can not keep up with events, and a backlog gets too large, the server will drop the connection.', }, ], }, commit: { type: 'object', + description: + 'Represents an update of repository state. Note that empty commits are allowed, which include no repo data changes, but an update to rev and signature.', required: [ 'seq', 'rebase', @@ -4146,34 +4285,45 @@ export const schemaDict = { properties: { seq: { type: 'integer', + description: 'The stream sequence number of this message.', }, rebase: { type: 'boolean', + description: 'DEPRECATED -- unused', }, tooBig: { type: 'boolean', + description: + 'Indicates that this commit contained too many ops, or data size was too large. Consumers will need to make a separate request to get missing data.', }, repo: { type: 'string', format: 'did', + description: 'The repo this event comes from.', }, commit: { type: 'cid-link', + description: 'Repo commit object CID.', }, prev: { type: 'cid-link', + description: + 'DEPRECATED -- unused. WARNING -- nullable and optional; stick with optional to ensure golang interoperability.', }, rev: { type: 'string', - description: 'The rev of the emitted commit.', + description: + 'The rev of the emitted commit. Note that this information is also in the commit object included in blocks, unless this is a tooBig event.', }, since: { type: 'string', - description: 'The rev of the last emitted commit from this repo.', + description: + 'The rev of the last emitted commit from this repo (if any).', }, blocks: { type: 'bytes', - description: 'CAR file containing relevant blocks.', + description: + 'CAR file containing relevant blocks, as a diff since the previous repo state.', maxLength: 1000000, }, ops: { @@ -4181,6 +4331,8 @@ export const schemaDict = { items: { type: 'ref', ref: 'lex:com.atproto.sync.subscribeRepos#repoOp', + description: + 'List of repo mutation operations in this commit (eg, records created, updated, or deleted).', }, maxLength: 200, }, @@ -4188,16 +4340,22 @@ export const schemaDict = { type: 'array', items: { type: 'cid-link', + description: + 'List of new blobs (by CID) referenced by records in this commit.', }, }, time: { type: 'string', format: 'datetime', + description: + 'Timestamp of when this message was originally broadcast.', }, }, }, handle: { type: 'object', + description: + "Represents an update of the account's handle, or transition to/from invalid state.", required: ['seq', 'did', 'handle', 'time'], properties: { seq: { @@ -4219,6 +4377,8 @@ export const schemaDict = { }, migrate: { type: 'object', + description: + 'Represents an account moving from one PDS instance to another. NOTE: not implemented; full account migration may introduce a new message instead.', required: ['seq', 'did', 'migrateTo', 'time'], nullable: ['migrateTo'], properties: { @@ -4240,6 +4400,7 @@ export const schemaDict = { }, tombstone: { type: 'object', + description: 'Indicates that an account has been deleted.', required: ['seq', 'did', 'time'], properties: { seq: { @@ -4270,8 +4431,7 @@ export const schemaDict = { }, repoOp: { type: 'object', - description: - "A repo operation, ie a write of a single record. For creates and updates, CID is the record's CID as of this operation. For deletes, it's null.", + description: 'A repo operation, ie a mutation of a single record.', required: ['action', 'path', 'cid'], nullable: ['cid'], properties: { @@ -4284,6 +4444,8 @@ export const schemaDict = { }, cid: { type: 'cid-link', + description: + 'For creates and updates, the new record CID. For deletions, null.', }, }, }, @@ -4324,7 +4486,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Fetch all labels from a labeler created after a certain date.', + 'Fetch all labels from a labeler created after a certain date. DEPRECATED: use queryLabels or subscribeLabels instead', parameters: { type: 'params', properties: { @@ -4440,7 +4602,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Transfer an account.', + description: + 'Transfer an account. NOTE: temporary method, necessarily how account migration will be implemented.', input: { encoding: 'application/json', schema: { @@ -4513,7 +4676,6 @@ export const schemaDict = { AppBskyActorDefs: { lexicon: 1, id: 'app.bsky.actor.defs', - description: 'A reference to an actor in the network.', defs: { profileViewBasic: { type: 'object', @@ -4646,6 +4808,8 @@ export const schemaDict = { }, 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', @@ -4731,6 +4895,9 @@ export const schemaDict = { format: 'at-uri', }, }, + timelineIndex: { + type: 'integer', + }, }, }, personalDetailsPref: { @@ -4815,7 +4982,8 @@ export const schemaDict = { 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: {}, @@ -4842,7 +5010,8 @@ export const schemaDict = { 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'], @@ -4850,6 +5019,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Handle or DID of account to fetch profile of.', }, }, }, @@ -4909,7 +5079,8 @@ export const schemaDict = { 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: { @@ -4952,7 +5123,7 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a profile.', + description: 'A declaration of a Bluesky account profile.', key: 'literal:self', record: { type: 'object', @@ -4964,21 +5135,28 @@ export const schemaDict = { }, 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: ['lex:com.atproto.label.defs#selfLabels'], }, }, @@ -5015,7 +5193,8 @@ export const schemaDict = { 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: { @@ -5067,7 +5246,8 @@ export const schemaDict = { 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: { @@ -5109,11 +5289,11 @@ export const schemaDict = { AppBskyEmbedExternal: { 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: { @@ -5177,7 +5357,7 @@ export const schemaDict = { AppBskyEmbedImages: { 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', @@ -5204,6 +5384,8 @@ export const schemaDict = { }, alt: { type: 'string', + description: + 'Alt text description of the image, for accessibility.', }, aspectRatio: { type: 'ref', @@ -5247,12 +5429,18 @@ export const schemaDict = { properties: { 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', @@ -5266,7 +5454,7 @@ export const schemaDict = { lexicon: 1, id: 'app.bsky.embed.record', description: - 'A representation of a record embedded in another form of content.', + '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', @@ -5312,6 +5500,7 @@ export const schemaDict = { }, value: { type: 'unknown', + description: 'The record data itself.', }, labels: { type: 'array', @@ -5376,7 +5565,7 @@ export const schemaDict = { lexicon: 1, id: 'app.bsky.embed.recordWithMedia', description: - 'A representation of a record embedded in another form of content, alongside other compatible embeds.', + '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', @@ -5475,6 +5664,8 @@ export const schemaDict = { }, 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', @@ -5735,7 +5926,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Get information about a feed generator, including policies and offered feed URIs.', + '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: { @@ -5790,7 +5981,8 @@ export const schemaDict = { 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', @@ -5824,6 +6016,7 @@ export const schemaDict = { }, labels: { type: 'union', + description: 'Self-label values', refs: ['lex:com.atproto.label.defs#selfLabels'], }, createdAt: { @@ -5841,7 +6034,8 @@ export const schemaDict = { 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'], @@ -5889,7 +6083,8 @@ export const schemaDict = { 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'], @@ -5945,7 +6140,8 @@ export const schemaDict = { 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'], @@ -5965,6 +6161,8 @@ export const schemaDict = { }, filter: { type: 'string', + description: + 'Combinations of post/repost types to include in response.', knownValues: [ 'posts_with_replies', 'posts_no_replies', @@ -6012,7 +6210,7 @@ export const schemaDict = { main: { type: 'query', description: - "Get a hydrated feed from an actor's selected feed generator.", + "Get a hydrated feed from an actor's selected feed generator. Implemented by App View.", parameters: { type: 'params', required: ['feed'], @@ -6065,7 +6263,8 @@ export const schemaDict = { 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'], @@ -6073,6 +6272,7 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: 'AT-URI of the feed generator record.', }, }, }, @@ -6088,9 +6288,13 @@ export const schemaDict = { }, 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.', }, }, }, @@ -6143,7 +6347,8 @@ export const schemaDict = { 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'], @@ -6151,6 +6356,8 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: + 'Reference to feed generator record describing the specific feed being requested.', }, limit: { type: 'integer', @@ -6196,7 +6403,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get the list of likes.', + description: + 'Get like records which reference a subject (by AT-URI and CID).', parameters: { type: 'params', required: ['uri'], @@ -6204,10 +6412,13 @@ export const schemaDict = { uri: { type: 'string', format: 'at-uri', + description: 'AT-URI of the subject (eg, a post record).', }, cid: { type: 'string', format: 'cid', + description: + 'CID of the subject record (aka, specific version of record), to filter likes.', }, limit: { type: 'integer', @@ -6274,7 +6485,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a view of a recent posts from actors in a list.', + description: + 'Get a feed of recent posts from a list (posts and reposts from any actors on the list). Does not require auth.', parameters: { type: 'params', required: ['list'], @@ -6282,6 +6494,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the list record.', }, limit: { type: 'integer', @@ -6327,7 +6540,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get posts in a thread.', + description: + 'Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.', parameters: { type: 'params', required: ['uri'], @@ -6335,15 +6549,20 @@ export const schemaDict = { uri: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to post record.', }, depth: { type: 'integer', + description: + 'How many levels of reply depth should be included in response.', default: 6, minimum: 0, maximum: 1000, }, parentHeight: { type: 'integer', + description: + 'How many levels of parent (and grandparent, etc) post to include.', default: 80, minimum: 0, maximum: 1000, @@ -6381,13 +6600,15 @@ export const schemaDict = { defs: { main: { type: 'query', - description: "Get a view of an actor's feed.", + description: + "Gets post views for a specified list of posts (by AT-URI). This is sometimes referred to as 'hydrating' a 'feed skeleton'.", parameters: { type: 'params', required: ['uris'], properties: { uris: { type: 'array', + description: 'List of post AT-URIs to return hydrated views for.', items: { type: 'string', format: 'at-uri', @@ -6421,7 +6642,7 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of reposts.', + description: 'Get a list of reposts for a given post.', parameters: { type: 'params', required: ['uri'], @@ -6429,10 +6650,13 @@ export const schemaDict = { uri: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) of post record', }, cid: { type: 'string', format: 'cid', + description: + 'If supplied, filters to reposts of specific version (by CID) of the post record.', }, limit: { type: 'integer', @@ -6481,7 +6705,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of suggested feeds for the viewer.', + description: + 'Get a list of suggested feeds (feed generators) for the requesting account.', parameters: { type: 'params', properties: { @@ -6524,12 +6749,15 @@ export const schemaDict = { defs: { main: { type: 'query', - description: "Get a view of the actor's home timeline.", + description: + "Get a view of the requesting account's home timeline. This is expected to be some form of reverse-chronological feed.", parameters: { type: 'params', properties: { algorithm: { type: 'string', + description: + "Variant 'algorithm' for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism.", }, limit: { type: 'integer', @@ -6570,7 +6798,7 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a like.', + description: "Record declaring a 'like' of a piece of subject content.", key: 'tid', record: { type: 'object', @@ -6595,7 +6823,7 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a post.', + description: 'Record containing a Bluesky post.', key: 'tid', record: { type: 'object', @@ -6605,10 +6833,12 @@ export const schemaDict = { type: 'string', maxLength: 3000, maxGraphemes: 300, + description: + 'The primary post content. May be an empty string, if there are embeds.', }, entities: { type: 'array', - description: 'Deprecated: replaced by app.bsky.richtext.facet.', + description: 'DEPRECATED: replaced by app.bsky.richtext.facet.', items: { type: 'ref', ref: 'lex:app.bsky.feed.post#entity', @@ -6616,6 +6846,8 @@ export const schemaDict = { }, facets: { type: 'array', + description: + 'Annotations of text (mentions, URLs, hashtags, etc)', items: { type: 'ref', ref: 'lex:app.bsky.richtext.facet', @@ -6636,6 +6868,8 @@ export const schemaDict = { }, langs: { type: 'array', + description: + 'Indicates human language of post primary text content.', maxLength: 3, items: { type: 'string', @@ -6644,21 +6878,26 @@ export const schemaDict = { }, labels: { type: 'union', + description: + 'Self-label values for this post. Effectively content warnings.', refs: ['lex:com.atproto.label.defs#selfLabels'], }, tags: { type: 'array', + description: + 'Additional hashtags, in addition to any included in post text and facets.', maxLength: 8, items: { type: 'string', maxLength: 640, maxGraphemes: 64, }, - description: 'Additional non-inline tags describing this post.', }, createdAt: { type: 'string', format: 'datetime', + description: + 'Client-declared timestamp when this post was originally created.', }, }, }, @@ -6718,7 +6957,8 @@ export const schemaDict = { id: 'app.bsky.feed.repost', defs: { main: { - description: 'A declaration of a repost.', + description: + "Record representing a 'repost' of an existing Bluesky post.", type: 'record', key: 'tid', record: { @@ -6744,7 +6984,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Find posts matching search criteria.', + description: + 'Find posts matching search criteria, returning views of those posts.', parameters: { type: 'params', required: ['q'], @@ -6807,7 +7048,7 @@ export const schemaDict = { type: 'record', key: 'tid', description: - "Defines interaction gating rules for a thread. The rkey of the threadgate record should match the rkey of the thread's root post.", + "Record defining interaction gating rules for a thread (aka, reply controls). The record key (rkey) of the threadgate record must match the record key of the thread's root post, and that record must be in the same repository..", record: { type: 'object', required: ['post', 'createdAt'], @@ -6815,6 +7056,7 @@ export const schemaDict = { post: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the post record.', }, allow: { type: 'array', @@ -6864,7 +7106,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a block.', + description: + "Record declaring a 'block' relationship against another account. NOTE: blocks are public in Bluesky; see blog posts for details.", key: 'tid', record: { type: 'object', @@ -6873,6 +7116,7 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'DID of the account to be blocked.', }, createdAt: { type: 'string', @@ -7061,7 +7305,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a social follow.', + description: + "Record declaring a social 'follow' relationship of another account. Duplicate follows will be ignored by the AppView.", key: 'tid', record: { type: 'object', @@ -7086,7 +7331,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of who the actor is blocking.', + description: + 'Enumerates which accounts the requesting account is currently blocking. Requires auth.', parameters: { type: 'params', properties: { @@ -7129,7 +7375,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: "Get a list of an actor's followers.", + description: + 'Enumerates accounts which follow a specified account (actor).', parameters: { type: 'params', required: ['actor'], @@ -7181,7 +7428,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of who the actor follows.', + description: + 'Enumerates accounts which a specified account (actor) follows.', parameters: { type: 'params', required: ['actor'], @@ -7233,7 +7481,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of actors.', + description: + "Gets a 'view' (with additional context) of a specified list.", parameters: { type: 'params', required: ['list'], @@ -7241,6 +7490,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) of the list record to hydrate.', }, limit: { type: 'integer', @@ -7285,7 +7535,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get lists that the actor is blocking.', + description: + 'Get mod lists that the requesting account (actor) is blocking. Requires auth.', parameters: { type: 'params', properties: { @@ -7328,7 +7579,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get lists that the actor is muting.', + description: + 'Enumerates mod lists that the requesting account (actor) currently has muted. Requires auth.', parameters: { type: 'params', properties: { @@ -7371,7 +7623,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of lists that belong to an actor.', + description: + 'Enumerates the lists created by a specified account (actor).', parameters: { type: 'params', required: ['actor'], @@ -7379,6 +7632,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'The account (actor) to enumerate lists from.', }, limit: { type: 'integer', @@ -7419,7 +7673,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of who the actor mutes.', + description: + 'Enumerates accounts that the requesting account (actor) currently has muted. Requires auth.', parameters: { type: 'params', properties: { @@ -7463,7 +7718,7 @@ export const schemaDict = { main: { type: 'query', description: - 'Enumerates public relationships between one account, and a list of other accounts', + 'Enumerates public relationships between one account, and a list of other accounts. Does not require auth.', parameters: { type: 'params', required: ['actor'], @@ -7471,9 +7726,12 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Primary account requesting relationships for.', }, others: { type: 'array', + description: + "List of 'other' accounts to be related back to the primary.", maxLength: 30, items: { type: 'string', @@ -7521,7 +7779,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get suggested follows related to a given actor.', + description: + 'Enumerates follows similar to a given account (actor). Expected use is to recommend additional accounts immediately after following one account.', parameters: { type: 'params', required: ['actor'], @@ -7557,7 +7816,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A declaration of a list of actors.', + description: + 'Record representing a list of accounts (actors). Scope includes both moderation-oriented lists and curration-oriented lists.', key: 'tid', record: { type: 'object', @@ -7565,12 +7825,15 @@ export const schemaDict = { properties: { purpose: { type: 'ref', + description: + 'Defines the purpose of the list (aka, moderation-oriented or curration-oriented)', ref: 'lex:app.bsky.graph.defs#listPurpose', }, name: { type: 'string', maxLength: 64, minLength: 1, + description: 'Display name for list; can not be empty.', }, description: { type: 'string', @@ -7608,7 +7871,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'A block of an entire list of actors.', + description: + 'Record representing a block relationship against an entire an entire list of accounts (actors).', key: 'tid', record: { type: 'object', @@ -7617,6 +7881,7 @@ export const schemaDict = { subject: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the mod list record.', }, createdAt: { type: 'string', @@ -7633,7 +7898,8 @@ export const schemaDict = { defs: { main: { type: 'record', - description: 'An item under a declared list of actors.', + description: + "Record representing an account's inclusion on a specific list. The AppView will ignore duplicate listitem records.", key: 'tid', record: { type: 'object', @@ -7642,10 +7908,13 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'The account which is included on the list.', }, list: { type: 'string', format: 'at-uri', + description: + 'Reference (AT-URI) to the list record (app.bsky.graph.list).', }, createdAt: { type: 'string', @@ -7662,7 +7931,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Mute an actor by DID or handle.', + description: + 'Creates a mute relationship for the specified account. Mutes are private in Bluesky. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7685,7 +7955,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Mute a list of actors.', + description: + 'Creates a mute relationship for the specified list of accounts. Mutes are private in Bluesky. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7708,7 +7979,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Unmute an actor by DID or handle.', + description: 'Unmutes the specified account. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7731,7 +8002,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Unmute a list of actors.', + description: 'Unmutes the specified list of accounts. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7754,7 +8025,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get the count of unread notifications.', + description: + 'Count the number of unread notifications for the requesting account. Requires auth.', parameters: { type: 'params', properties: { @@ -7785,7 +8057,8 @@ export const schemaDict = { defs: { main: { type: 'query', - description: 'Get a list of notifications.', + description: + 'Enumerate notifications for the requesting account. Requires auth.', parameters: { type: 'params', properties: { @@ -7896,7 +8169,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Register for push notifications with a service.', + description: + 'Register to receive push notifications, via a specified service, for the requesting account. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7929,7 +8203,8 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Notify server that the user has seen notifications.', + description: + 'Notify server that the requesting account has seen notifications. Requires auth.', input: { encoding: 'application/json', schema: { @@ -7952,6 +8227,7 @@ export const schemaDict = { defs: { main: { type: 'object', + description: 'Annotation of a sub-string within rich text.', required: ['index', 'features'], properties: { index: { @@ -7973,7 +8249,8 @@ export const schemaDict = { }, mention: { type: 'object', - description: 'A facet feature for actor mentions.', + description: + "Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID.", required: ['did'], properties: { did: { @@ -7984,7 +8261,8 @@ export const schemaDict = { }, link: { type: 'object', - description: 'A facet feature for links.', + description: + 'Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.', required: ['uri'], properties: { uri: { @@ -7995,7 +8273,8 @@ export const schemaDict = { }, tag: { type: 'object', - description: 'A hashtag.', + description: + "Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').", required: ['tag'], properties: { tag: { @@ -8008,7 +8287,7 @@ export const schemaDict = { byteSlice: { type: 'object', description: - 'A text segment. Start is inclusive, end is exclusive. Indices are for utf8-encoded strings.', + 'Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.', required: ['byteStart', 'byteEnd'], properties: { byteStart: { diff --git a/packages/pds/src/lexicon/types/app/bsky/actor/defs.ts b/packages/pds/src/lexicon/types/app/bsky/actor/defs.ts index 8cdcafcb72f..a802f70f44b 100644 --- a/packages/pds/src/lexicon/types/app/bsky/actor/defs.ts +++ b/packages/pds/src/lexicon/types/app/bsky/actor/defs.ts @@ -82,6 +82,7 @@ export function validateProfileViewDetailed(v: unknown): ValidationResult { return lexicons.validate('app.bsky.actor.defs#profileViewDetailed', v) } +/** Metadata about the requesting account's relationship with the subject account. Only has meaningful content for authed requests. */ export interface ViewerState { muted?: boolean mutedByList?: AppBskyGraphDefs.ListViewBasic @@ -154,6 +155,7 @@ export function validateContentLabelPref(v: unknown): ValidationResult { export interface SavedFeedsPref { pinned: string[] saved: string[] + timelineIndex?: number [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/app/bsky/actor/getProfile.ts b/packages/pds/src/lexicon/types/app/bsky/actor/getProfile.ts index be58c73a233..5a7b1f25bfc 100644 --- a/packages/pds/src/lexicon/types/app/bsky/actor/getProfile.ts +++ b/packages/pds/src/lexicon/types/app/bsky/actor/getProfile.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyActorDefs from './defs' export interface QueryParams { + /** Handle or DID of account to fetch profile of. */ actor: string } diff --git a/packages/pds/src/lexicon/types/app/bsky/actor/profile.ts b/packages/pds/src/lexicon/types/app/bsky/actor/profile.ts index 7dbc4c1ccec..8810ce7bed9 100644 --- a/packages/pds/src/lexicon/types/app/bsky/actor/profile.ts +++ b/packages/pds/src/lexicon/types/app/bsky/actor/profile.ts @@ -9,8 +9,11 @@ import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs' export interface Record { displayName?: string + /** Free-form profile description text. */ description?: string + /** Small image to be displayed next to posts from account. AKA, 'profile picture' */ avatar?: BlobRef + /** Larger horizontal image to display behind profile view. */ banner?: BlobRef labels?: | ComAtprotoLabelDefs.SelfLabels diff --git a/packages/pds/src/lexicon/types/app/bsky/embed/external.ts b/packages/pds/src/lexicon/types/app/bsky/embed/external.ts index f42a6cfd95c..b137ee4b6f5 100644 --- a/packages/pds/src/lexicon/types/app/bsky/embed/external.ts +++ b/packages/pds/src/lexicon/types/app/bsky/embed/external.ts @@ -6,6 +6,7 @@ import { lexicons } from '../../../../lexicons' import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' +/** A representation of some externally linked content (eg, a URL and 'card'), embedded in a Bluesky record (eg, a post). */ export interface Main { external: External [k: string]: unknown diff --git a/packages/pds/src/lexicon/types/app/bsky/embed/images.ts b/packages/pds/src/lexicon/types/app/bsky/embed/images.ts index 4864fad3dea..96399867a1a 100644 --- a/packages/pds/src/lexicon/types/app/bsky/embed/images.ts +++ b/packages/pds/src/lexicon/types/app/bsky/embed/images.ts @@ -26,6 +26,7 @@ export function validateMain(v: unknown): ValidationResult { export interface Image { image: BlobRef + /** Alt text description of the image, for accessibility. */ alt: string aspectRatio?: AspectRatio [k: string]: unknown @@ -76,8 +77,11 @@ export function validateView(v: unknown): ValidationResult { } export interface ViewImage { + /** Fully-qualified URL where a thumbnail of the image can be fetched. For example, CDN location provided by the App View. */ thumb: string + /** 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. */ fullsize: string + /** Alt text description of the image, for accessibility. */ alt: string aspectRatio?: AspectRatio [k: string]: unknown diff --git a/packages/pds/src/lexicon/types/app/bsky/embed/record.ts b/packages/pds/src/lexicon/types/app/bsky/embed/record.ts index cea5742a45e..dbe7f13152b 100644 --- a/packages/pds/src/lexicon/types/app/bsky/embed/record.ts +++ b/packages/pds/src/lexicon/types/app/bsky/embed/record.ts @@ -57,6 +57,7 @@ export interface ViewRecord { uri: string cid: string author: AppBskyActorDefs.ProfileViewBasic + /** The record data itself. */ value: {} labels?: ComAtprotoLabelDefs.Label[] embeds?: ( diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/defs.ts b/packages/pds/src/lexicon/types/app/bsky/feed/defs.ts index 382d3f58ecf..261d8a622ec 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/defs.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/defs.ts @@ -45,6 +45,7 @@ export function validatePostView(v: unknown): ValidationResult { return lexicons.validate('app.bsky.feed.defs#postView', v) } +/** Metadata about the requesting account's relationship with the subject content. Only has meaningful content for authed requests. */ export interface ViewerState { repost?: string like?: string diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts b/packages/pds/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts index 8f8e038c71f..017c7a6a2d4 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts @@ -13,6 +13,7 @@ export interface QueryParams { actor: string limit: number cursor?: string + /** Combinations of post/repost types to include in response. */ filter: | 'posts_with_replies' | 'posts_no_replies' diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts b/packages/pds/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts index b65a5151d46..7ab89057a8c 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** AT-URI of the feed generator record. */ feed: string } @@ -17,7 +18,9 @@ export type InputSchema = undefined export interface OutputSchema { view: AppBskyFeedDefs.GeneratorView + /** Indicates whether the feed generator service has been online recently, or else seems to be inactive. */ isOnline: boolean + /** Indicates whether the feed generator service is compatible with the record declaration. */ isValid: boolean [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts b/packages/pds/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts index ab1911ecb87..ca1cef20f08 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Reference to feed generator record describing the specific feed being requested. */ feed: string limit: number cursor?: string diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/getLikes.ts b/packages/pds/src/lexicon/types/app/bsky/feed/getLikes.ts index c7e8c860bd6..275d99bba3d 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/getLikes.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/getLikes.ts @@ -10,7 +10,9 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyActorDefs from '../actor/defs' export interface QueryParams { + /** AT-URI of the subject (eg, a post record). */ uri: string + /** CID of the subject record (aka, specific version of record), to filter likes. */ cid?: string limit: number cursor?: string diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/getListFeed.ts b/packages/pds/src/lexicon/types/app/bsky/feed/getListFeed.ts index ab157788f72..84e12deaa92 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/getListFeed.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/getListFeed.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Reference (AT-URI) to the list record. */ list: string limit: number cursor?: string diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/getPostThread.ts b/packages/pds/src/lexicon/types/app/bsky/feed/getPostThread.ts index 9e81da0eff6..ae232fd91a2 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/getPostThread.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/getPostThread.ts @@ -10,8 +10,11 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Reference (AT-URI) to post record. */ uri: string + /** How many levels of reply depth should be included in response. */ depth: number + /** How many levels of parent (and grandparent, etc) post to include. */ parentHeight: number } diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/getPosts.ts b/packages/pds/src/lexicon/types/app/bsky/feed/getPosts.ts index 439e2132201..85000c74787 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/getPosts.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/getPosts.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** List of post AT-URIs to return hydrated views for. */ uris: string[] } diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/getRepostedBy.ts b/packages/pds/src/lexicon/types/app/bsky/feed/getRepostedBy.ts index 6dea2b753c7..40e008815d9 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/getRepostedBy.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/getRepostedBy.ts @@ -10,7 +10,9 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyActorDefs from '../actor/defs' export interface QueryParams { + /** Reference (AT-URI) of post record */ uri: string + /** If supplied, filters to reposts of specific version (by CID) of the post record. */ cid?: string limit: number cursor?: string diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/getTimeline.ts b/packages/pds/src/lexicon/types/app/bsky/feed/getTimeline.ts index f37def5808e..5202c9eb6e3 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/getTimeline.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/getTimeline.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyFeedDefs from './defs' export interface QueryParams { + /** Variant 'algorithm' for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism. */ algorithm?: string limit: number cursor?: string diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/post.ts b/packages/pds/src/lexicon/types/app/bsky/feed/post.ts index 93870b4452d..881e3d199aa 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/post.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/post.ts @@ -14,9 +14,11 @@ import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs' import * as ComAtprotoRepoStrongRef from '../../../com/atproto/repo/strongRef' export interface Record { + /** The primary post content. May be an empty string, if there are embeds. */ text: string - /** Deprecated: replaced by app.bsky.richtext.facet. */ + /** DEPRECATED: replaced by app.bsky.richtext.facet. */ entities?: Entity[] + /** Annotations of text (mentions, URLs, hashtags, etc) */ facets?: AppBskyRichtextFacet.Main[] reply?: ReplyRef embed?: @@ -25,12 +27,14 @@ export interface Record { | AppBskyEmbedRecord.Main | AppBskyEmbedRecordWithMedia.Main | { $type: string; [k: string]: unknown } + /** Indicates human language of post primary text content. */ langs?: string[] labels?: | ComAtprotoLabelDefs.SelfLabels | { $type: string; [k: string]: unknown } - /** Additional non-inline tags describing this post. */ + /** Additional hashtags, in addition to any included in post text and facets. */ tags?: string[] + /** Client-declared timestamp when this post was originally created. */ createdAt: string [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/app/bsky/feed/threadgate.ts b/packages/pds/src/lexicon/types/app/bsky/feed/threadgate.ts index 6a190d6e98a..e14140d5609 100644 --- a/packages/pds/src/lexicon/types/app/bsky/feed/threadgate.ts +++ b/packages/pds/src/lexicon/types/app/bsky/feed/threadgate.ts @@ -7,6 +7,7 @@ import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' export interface Record { + /** Reference (AT-URI) to the post record. */ post: string allow?: ( | MentionRule diff --git a/packages/pds/src/lexicon/types/app/bsky/graph/block.ts b/packages/pds/src/lexicon/types/app/bsky/graph/block.ts index 947463af422..b7f19f126b7 100644 --- a/packages/pds/src/lexicon/types/app/bsky/graph/block.ts +++ b/packages/pds/src/lexicon/types/app/bsky/graph/block.ts @@ -7,6 +7,7 @@ import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' export interface Record { + /** DID of the account to be blocked. */ subject: string createdAt: string [k: string]: unknown diff --git a/packages/pds/src/lexicon/types/app/bsky/graph/getList.ts b/packages/pds/src/lexicon/types/app/bsky/graph/getList.ts index 6b30cd7faa9..864a81b3833 100644 --- a/packages/pds/src/lexicon/types/app/bsky/graph/getList.ts +++ b/packages/pds/src/lexicon/types/app/bsky/graph/getList.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyGraphDefs from './defs' export interface QueryParams { + /** Reference (AT-URI) of the list record to hydrate. */ list: string limit: number cursor?: string diff --git a/packages/pds/src/lexicon/types/app/bsky/graph/getLists.ts b/packages/pds/src/lexicon/types/app/bsky/graph/getLists.ts index 6bcb3134a47..dc0c4f18bea 100644 --- a/packages/pds/src/lexicon/types/app/bsky/graph/getLists.ts +++ b/packages/pds/src/lexicon/types/app/bsky/graph/getLists.ts @@ -10,6 +10,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyGraphDefs from './defs' export interface QueryParams { + /** The account (actor) to enumerate lists from. */ actor: string limit: number cursor?: string diff --git a/packages/pds/src/lexicon/types/app/bsky/graph/getRelationships.ts b/packages/pds/src/lexicon/types/app/bsky/graph/getRelationships.ts index 0125414ccd4..bd6b6e765ed 100644 --- a/packages/pds/src/lexicon/types/app/bsky/graph/getRelationships.ts +++ b/packages/pds/src/lexicon/types/app/bsky/graph/getRelationships.ts @@ -10,7 +10,9 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' import * as AppBskyGraphDefs from './defs' export interface QueryParams { + /** Primary account requesting relationships for. */ actor: string + /** List of 'other' accounts to be related back to the primary. */ others?: string[] } diff --git a/packages/pds/src/lexicon/types/app/bsky/graph/list.ts b/packages/pds/src/lexicon/types/app/bsky/graph/list.ts index 36a7fb17a3f..91c8ccee5bb 100644 --- a/packages/pds/src/lexicon/types/app/bsky/graph/list.ts +++ b/packages/pds/src/lexicon/types/app/bsky/graph/list.ts @@ -11,6 +11,7 @@ import * as ComAtprotoLabelDefs from '../../../com/atproto/label/defs' export interface Record { purpose: AppBskyGraphDefs.ListPurpose + /** Display name for list; can not be empty. */ name: string description?: string descriptionFacets?: AppBskyRichtextFacet.Main[] diff --git a/packages/pds/src/lexicon/types/app/bsky/graph/listblock.ts b/packages/pds/src/lexicon/types/app/bsky/graph/listblock.ts index 59f2e057eb5..592778c7a51 100644 --- a/packages/pds/src/lexicon/types/app/bsky/graph/listblock.ts +++ b/packages/pds/src/lexicon/types/app/bsky/graph/listblock.ts @@ -7,6 +7,7 @@ import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' export interface Record { + /** Reference (AT-URI) to the mod list record. */ subject: string createdAt: string [k: string]: unknown diff --git a/packages/pds/src/lexicon/types/app/bsky/graph/listitem.ts b/packages/pds/src/lexicon/types/app/bsky/graph/listitem.ts index 69eff329ed4..5e93b34a111 100644 --- a/packages/pds/src/lexicon/types/app/bsky/graph/listitem.ts +++ b/packages/pds/src/lexicon/types/app/bsky/graph/listitem.ts @@ -7,7 +7,9 @@ import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' export interface Record { + /** The account which is included on the list. */ subject: string + /** Reference (AT-URI) to the list record (app.bsky.graph.list). */ list: string createdAt: string [k: string]: unknown diff --git a/packages/pds/src/lexicon/types/app/bsky/richtext/facet.ts b/packages/pds/src/lexicon/types/app/bsky/richtext/facet.ts index 2c5b2d723a9..139b5382caf 100644 --- a/packages/pds/src/lexicon/types/app/bsky/richtext/facet.ts +++ b/packages/pds/src/lexicon/types/app/bsky/richtext/facet.ts @@ -6,6 +6,7 @@ import { lexicons } from '../../../../lexicons' import { isObj, hasProp } from '../../../../util' import { CID } from 'multiformats/cid' +/** Annotation of a sub-string within rich text. */ export interface Main { index: ByteSlice features: (Mention | Link | Tag | { $type: string; [k: string]: unknown })[] @@ -25,7 +26,7 @@ export function validateMain(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#main', v) } -/** A facet feature for actor mentions. */ +/** Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID. */ export interface Mention { did: string [k: string]: unknown @@ -43,7 +44,7 @@ export function validateMention(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#mention', v) } -/** A facet feature for links. */ +/** Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL. */ export interface Link { uri: string [k: string]: unknown @@ -61,7 +62,7 @@ export function validateLink(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#link', v) } -/** A hashtag. */ +/** Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags'). */ export interface Tag { tag: string [k: string]: unknown @@ -77,7 +78,7 @@ export function validateTag(v: unknown): ValidationResult { return lexicons.validate('app.bsky.richtext.facet#tag', v) } -/** A text segment. Start is inclusive, end is exclusive. Indices are for utf8-encoded strings. */ +/** Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets. */ export interface ByteSlice { byteStart: number byteEnd: number diff --git a/packages/pds/src/lexicon/types/com/atproto/admin/defs.ts b/packages/pds/src/lexicon/types/com/atproto/admin/defs.ts index 2fab0bc19a4..a713a635635 100644 --- a/packages/pds/src/lexicon/types/com/atproto/admin/defs.ts +++ b/packages/pds/src/lexicon/types/com/atproto/admin/defs.ts @@ -156,6 +156,7 @@ export interface SubjectStatusView { /** True indicates that the a previously taken moderator action was appealed against, by the author of the content. False indicates last appeal was resolved by moderators. */ appealed?: boolean suspendUntil?: string + tags?: string[] [k: string]: unknown } @@ -720,6 +721,29 @@ export function validateModEventEmail(v: unknown): ValidationResult { return lexicons.validate('com.atproto.admin.defs#modEventEmail', v) } +/** Add/Remove a tag on a subject */ +export interface ModEventTag { + /** Tags to be added to the subject. If already exists, won't be duplicated. */ + add: string[] + /** Tags to be removed to the subject. Ignores a tag If it doesn't exist, won't be duplicated. */ + remove: string[] + /** Additional comment about added/removed tags. */ + comment?: string + [k: string]: unknown +} + +export function isModEventTag(v: unknown): v is ModEventTag { + return ( + isObj(v) && + hasProp(v, '$type') && + v.$type === 'com.atproto.admin.defs#modEventTag' + ) +} + +export function validateModEventTag(v: unknown): ValidationResult { + return lexicons.validate('com.atproto.admin.defs#modEventTag', v) +} + export interface CommunicationTemplateView { id: string /** Name of the template. */ diff --git a/packages/pds/src/lexicon/types/com/atproto/admin/emitModerationEvent.ts b/packages/pds/src/lexicon/types/com/atproto/admin/emitModerationEvent.ts index 3c0acabd0eb..99d08c7f1b7 100644 --- a/packages/pds/src/lexicon/types/com/atproto/admin/emitModerationEvent.ts +++ b/packages/pds/src/lexicon/types/com/atproto/admin/emitModerationEvent.ts @@ -24,6 +24,7 @@ export interface InputSchema { | ComAtprotoAdminDefs.ModEventReverseTakedown | ComAtprotoAdminDefs.ModEventUnmute | ComAtprotoAdminDefs.ModEventEmail + | ComAtprotoAdminDefs.ModEventTag | { $type: string; [k: string]: unknown } subject: | ComAtprotoAdminDefs.RepoRef diff --git a/packages/pds/src/lexicon/types/com/atproto/admin/queryModerationEvents.ts b/packages/pds/src/lexicon/types/com/atproto/admin/queryModerationEvents.ts index df07cfaf2da..9f4738578aa 100644 --- a/packages/pds/src/lexicon/types/com/atproto/admin/queryModerationEvents.ts +++ b/packages/pds/src/lexicon/types/com/atproto/admin/queryModerationEvents.ts @@ -31,6 +31,10 @@ export interface QueryParams { addedLabels?: string[] /** If specified, only events where all of these labels were removed are returned */ removedLabels?: string[] + /** If specified, only events where all of these tags were added are returned */ + addedTags?: string[] + /** If specified, only events where all of these tags were removed are returned */ + removedTags?: string[] reportTypes?: string[] cursor?: string } diff --git a/packages/pds/src/lexicon/types/com/atproto/admin/queryModerationStatuses.ts b/packages/pds/src/lexicon/types/com/atproto/admin/queryModerationStatuses.ts index 0cc21c25352..f5031d25117 100644 --- a/packages/pds/src/lexicon/types/com/atproto/admin/queryModerationStatuses.ts +++ b/packages/pds/src/lexicon/types/com/atproto/admin/queryModerationStatuses.ts @@ -35,6 +35,8 @@ export interface QueryParams { /** Get subjects in unresolved appealed status */ appealed?: boolean limit: number + tags?: string[] + excludeTags?: string[] cursor?: string } diff --git a/packages/pds/src/lexicon/types/com/atproto/identity/updateHandle.ts b/packages/pds/src/lexicon/types/com/atproto/identity/updateHandle.ts index 6782a68ed54..f451d1f57c7 100644 --- a/packages/pds/src/lexicon/types/com/atproto/identity/updateHandle.ts +++ b/packages/pds/src/lexicon/types/com/atproto/identity/updateHandle.ts @@ -11,6 +11,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { + /** The new handle. */ handle: string [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/com/atproto/label/subscribeLabels.ts b/packages/pds/src/lexicon/types/com/atproto/label/subscribeLabels.ts index 9d4b4441ae0..6034b35d895 100644 --- a/packages/pds/src/lexicon/types/com/atproto/label/subscribeLabels.ts +++ b/packages/pds/src/lexicon/types/com/atproto/label/subscribeLabels.ts @@ -10,7 +10,7 @@ import { IncomingMessage } from 'http' import * as ComAtprotoLabelDefs from './defs' export interface QueryParams { - /** The last known event to backfill from. */ + /** The last known event seq number to backfill from. */ cursor?: number } diff --git a/packages/pds/src/lexicon/types/com/atproto/moderation/createReport.ts b/packages/pds/src/lexicon/types/com/atproto/moderation/createReport.ts index c1335eb3d1f..aa3f810a91c 100644 --- a/packages/pds/src/lexicon/types/com/atproto/moderation/createReport.ts +++ b/packages/pds/src/lexicon/types/com/atproto/moderation/createReport.ts @@ -15,6 +15,7 @@ export interface QueryParams {} export interface InputSchema { reasonType: ComAtprotoModerationDefs.ReasonType + /** Additional context about the content and violation. */ reason?: string subject: | ComAtprotoAdminDefs.RepoRef diff --git a/packages/pds/src/lexicon/types/com/atproto/repo/applyWrites.ts b/packages/pds/src/lexicon/types/com/atproto/repo/applyWrites.ts index 7bdb6dc2ed1..3956d7c3048 100644 --- a/packages/pds/src/lexicon/types/com/atproto/repo/applyWrites.ts +++ b/packages/pds/src/lexicon/types/com/atproto/repo/applyWrites.ts @@ -11,11 +11,12 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string - /** Flag for validating the records. */ + /** Can be set to 'false' to skip Lexicon schema validation of record data, for all operations. */ validate: boolean writes: (Create | Update | Delete)[] + /** If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations. */ swapCommit?: string [k: string]: unknown } @@ -43,7 +44,7 @@ export type Handler = ( ctx: HandlerReqCtx, ) => Promise | HandlerOutput -/** Create a new record. */ +/** Operation which creates a new record. */ export interface Create { collection: string rkey?: string @@ -63,7 +64,7 @@ export function validateCreate(v: unknown): ValidationResult { return lexicons.validate('com.atproto.repo.applyWrites#create', v) } -/** Update an existing record. */ +/** Operation which updates an existing record. */ export interface Update { collection: string rkey: string @@ -83,7 +84,7 @@ export function validateUpdate(v: unknown): ValidationResult { return lexicons.validate('com.atproto.repo.applyWrites#update', v) } -/** Delete an existing record. */ +/** Operation which deletes an existing record. */ export interface Delete { collection: string rkey: string diff --git a/packages/pds/src/lexicon/types/com/atproto/repo/createRecord.ts b/packages/pds/src/lexicon/types/com/atproto/repo/createRecord.ts index 666b91c828d..55cc95d0ad7 100644 --- a/packages/pds/src/lexicon/types/com/atproto/repo/createRecord.ts +++ b/packages/pds/src/lexicon/types/com/atproto/repo/createRecord.ts @@ -11,15 +11,15 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey?: string - /** Flag for validating the record. */ + /** Can be set to 'false' to skip Lexicon schema validation of record data. */ validate: boolean - /** The record to create. */ + /** The record itself. Must contain a $type field. */ record: {} /** Compare and swap with the previous commit by CID. */ swapCommit?: string diff --git a/packages/pds/src/lexicon/types/com/atproto/repo/deleteRecord.ts b/packages/pds/src/lexicon/types/com/atproto/repo/deleteRecord.ts index 65ee32d213d..3bb97be0aad 100644 --- a/packages/pds/src/lexicon/types/com/atproto/repo/deleteRecord.ts +++ b/packages/pds/src/lexicon/types/com/atproto/repo/deleteRecord.ts @@ -11,11 +11,11 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey: string /** Compare and swap with the previous record by CID. */ swapRecord?: string diff --git a/packages/pds/src/lexicon/types/com/atproto/repo/describeRepo.ts b/packages/pds/src/lexicon/types/com/atproto/repo/describeRepo.ts index 38b9c01ef1c..749bedcfeb7 100644 --- a/packages/pds/src/lexicon/types/com/atproto/repo/describeRepo.ts +++ b/packages/pds/src/lexicon/types/com/atproto/repo/describeRepo.ts @@ -18,8 +18,11 @@ export type InputSchema = undefined export interface OutputSchema { handle: string did: string + /** The complete DID document for this account. */ didDoc: {} + /** List of all the collections (NSIDs) for which this repo contains at least one record. */ collections: string[] + /** Indicates if handle is currently valid (resolves bi-directionally) */ handleIsCorrect: boolean [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/com/atproto/repo/getRecord.ts b/packages/pds/src/lexicon/types/com/atproto/repo/getRecord.ts index 345dde29a53..1a737a848be 100644 --- a/packages/pds/src/lexicon/types/com/atproto/repo/getRecord.ts +++ b/packages/pds/src/lexicon/types/com/atproto/repo/getRecord.ts @@ -13,7 +13,7 @@ export interface QueryParams { repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey: string /** The CID of the version of the record. If not specified, then return the most recent version. */ cid?: string diff --git a/packages/pds/src/lexicon/types/com/atproto/repo/putRecord.ts b/packages/pds/src/lexicon/types/com/atproto/repo/putRecord.ts index de93e2e9cf7..193841a2294 100644 --- a/packages/pds/src/lexicon/types/com/atproto/repo/putRecord.ts +++ b/packages/pds/src/lexicon/types/com/atproto/repo/putRecord.ts @@ -11,17 +11,17 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The handle or DID of the repo. */ + /** The handle or DID of the repo (aka, current account). */ repo: string /** The NSID of the record collection. */ collection: string - /** The key of the record. */ + /** The Record Key. */ rkey: string - /** Flag for validating the record. */ + /** Can be set to 'false' to skip Lexicon schema validation of record data. */ validate: boolean /** The record to write. */ record: {} - /** Compare and swap with the previous record by CID. */ + /** Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation */ swapRecord?: string | null /** Compare and swap with the previous commit by CID. */ swapCommit?: string diff --git a/packages/pds/src/lexicon/types/com/atproto/server/createAccount.ts b/packages/pds/src/lexicon/types/com/atproto/server/createAccount.ts index bceb61546cf..6e9b2f9f3c2 100644 --- a/packages/pds/src/lexicon/types/com/atproto/server/createAccount.ts +++ b/packages/pds/src/lexicon/types/com/atproto/server/createAccount.ts @@ -12,22 +12,30 @@ export interface QueryParams {} export interface InputSchema { email?: string + /** Requested handle for the account. */ handle: string + /** Pre-existing atproto DID, being imported to a new account. */ did?: string inviteCode?: string verificationCode?: string verificationPhone?: string + /** Initial account password. May need to meet instance-specific password strength requirements. */ password?: string + /** DID PLC rotation key (aka, recovery key) to be included in PLC creation operation. */ recoveryKey?: string + /** A signed DID PLC operation to be submitted as part of importing an existing account to this instance. NOTE: this optional field may be updated when full account migration is implemented. */ plcOp?: {} [k: string]: unknown } +/** Account login session returned on successful account creation. */ export interface OutputSchema { accessJwt: string refreshJwt: string handle: string + /** The DID of the new account. */ did: string + /** Complete DID document. */ didDoc?: {} [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/com/atproto/server/createAppPassword.ts b/packages/pds/src/lexicon/types/com/atproto/server/createAppPassword.ts index 474846546fe..dcc5178ecfa 100644 --- a/packages/pds/src/lexicon/types/com/atproto/server/createAppPassword.ts +++ b/packages/pds/src/lexicon/types/com/atproto/server/createAppPassword.ts @@ -11,6 +11,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { + /** A short name for the App Password, to help distinguish them. */ name: string [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/com/atproto/server/describeServer.ts b/packages/pds/src/lexicon/types/com/atproto/server/describeServer.ts index 47be5b598b0..0e64c9d9708 100644 --- a/packages/pds/src/lexicon/types/com/atproto/server/describeServer.ts +++ b/packages/pds/src/lexicon/types/com/atproto/server/describeServer.ts @@ -13,8 +13,11 @@ export interface QueryParams {} export type InputSchema = undefined export interface OutputSchema { + /** If true, an invite code must be supplied to create an account on this instance. */ inviteCodeRequired?: boolean + /** If true, a phone verification token must be supplied to create an account on this instance. */ phoneVerificationRequired?: boolean + /** List of domain suffixes that can be used in account handles. */ availableUserDomains: string[] links?: Links [k: string]: unknown diff --git a/packages/pds/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts b/packages/pds/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts index 2dc551a477c..82c3ffa8c31 100644 --- a/packages/pds/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts +++ b/packages/pds/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts @@ -11,6 +11,7 @@ import * as ComAtprotoServerDefs from './defs' export interface QueryParams { includeUsed: boolean + /** Controls whether any new 'earned' but not 'created' invites should be created. */ createAvailable: boolean } diff --git a/packages/pds/src/lexicon/types/com/atproto/server/reserveSigningKey.ts b/packages/pds/src/lexicon/types/com/atproto/server/reserveSigningKey.ts index 0de1220f4b5..0ec1e80c77c 100644 --- a/packages/pds/src/lexicon/types/com/atproto/server/reserveSigningKey.ts +++ b/packages/pds/src/lexicon/types/com/atproto/server/reserveSigningKey.ts @@ -11,13 +11,13 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** The did to reserve a new did:key for */ + /** The DID to reserve a key for. */ did?: string [k: string]: unknown } export interface OutputSchema { - /** Public signing key in the form of a did:key. */ + /** The public key for the reserved signing key, in did:key serialization. */ signingKey: string [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/com/atproto/sync/getBlob.ts b/packages/pds/src/lexicon/types/com/atproto/sync/getBlob.ts index b3980fca500..93e50403f20 100644 --- a/packages/pds/src/lexicon/types/com/atproto/sync/getBlob.ts +++ b/packages/pds/src/lexicon/types/com/atproto/sync/getBlob.ts @@ -10,7 +10,7 @@ import { CID } from 'multiformats/cid' import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams { - /** The DID of the repo. */ + /** The DID of the account. */ did: string /** The CID of the blob to fetch */ cid: string diff --git a/packages/pds/src/lexicon/types/com/atproto/sync/getRecord.ts b/packages/pds/src/lexicon/types/com/atproto/sync/getRecord.ts index e27878ff5e6..c78ff8c2089 100644 --- a/packages/pds/src/lexicon/types/com/atproto/sync/getRecord.ts +++ b/packages/pds/src/lexicon/types/com/atproto/sync/getRecord.ts @@ -13,6 +13,7 @@ export interface QueryParams { /** The DID of the repo. */ did: string collection: string + /** Record Key */ rkey: string /** An optional past commit CID. */ commit?: string diff --git a/packages/pds/src/lexicon/types/com/atproto/sync/getRepo.ts b/packages/pds/src/lexicon/types/com/atproto/sync/getRepo.ts index e0ad53ded7c..0d426557c5f 100644 --- a/packages/pds/src/lexicon/types/com/atproto/sync/getRepo.ts +++ b/packages/pds/src/lexicon/types/com/atproto/sync/getRepo.ts @@ -12,7 +12,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams { /** The DID of the repo. */ did: string - /** The revision of the repo to catch up from. */ + /** The revision ('rev') of the repo to create a diff from. */ since?: string } diff --git a/packages/pds/src/lexicon/types/com/atproto/sync/listRepos.ts b/packages/pds/src/lexicon/types/com/atproto/sync/listRepos.ts index 12532860895..e5a8e2ca9d6 100644 --- a/packages/pds/src/lexicon/types/com/atproto/sync/listRepos.ts +++ b/packages/pds/src/lexicon/types/com/atproto/sync/listRepos.ts @@ -48,6 +48,7 @@ export type Handler = ( export interface Repo { did: string + /** Current repo commit CID */ head: string rev: string [k: string]: unknown diff --git a/packages/pds/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts b/packages/pds/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts index f9498e6691d..8a0af577c7c 100644 --- a/packages/pds/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts +++ b/packages/pds/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts @@ -11,7 +11,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** Hostname of the service that is notifying of update. */ + /** Hostname of the current service (usually a PDS) that is notifying of update. */ hostname: string [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/com/atproto/sync/requestCrawl.ts b/packages/pds/src/lexicon/types/com/atproto/sync/requestCrawl.ts index 2859e28fe69..31180aabf58 100644 --- a/packages/pds/src/lexicon/types/com/atproto/sync/requestCrawl.ts +++ b/packages/pds/src/lexicon/types/com/atproto/sync/requestCrawl.ts @@ -11,7 +11,7 @@ import { HandlerAuth, HandlerPipeThrough } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { - /** Hostname of the service that is requesting to be crawled. */ + /** Hostname of the current service (eg, PDS) that is requesting to be crawled. */ hostname: string [k: string]: unknown } diff --git a/packages/pds/src/lexicon/types/com/atproto/sync/subscribeRepos.ts b/packages/pds/src/lexicon/types/com/atproto/sync/subscribeRepos.ts index fb334778bf6..689ea76daee 100644 --- a/packages/pds/src/lexicon/types/com/atproto/sync/subscribeRepos.ts +++ b/packages/pds/src/lexicon/types/com/atproto/sync/subscribeRepos.ts @@ -9,7 +9,7 @@ import { HandlerAuth, ErrorFrame } from '@atproto/xrpc-server' import { IncomingMessage } from 'http' export interface QueryParams { - /** The last known event to backfill from. */ + /** The last known event seq number to backfill from. */ cursor?: number } @@ -32,21 +32,29 @@ export type Handler = ( ctx: HandlerReqCtx, ) => AsyncIterable +/** Represents an update of repository state. Note that empty commits are allowed, which include no repo data changes, but an update to rev and signature. */ export interface Commit { + /** The stream sequence number of this message. */ seq: number + /** DEPRECATED -- unused */ rebase: boolean + /** Indicates that this commit contained too many ops, or data size was too large. Consumers will need to make a separate request to get missing data. */ tooBig: boolean + /** The repo this event comes from. */ repo: string + /** Repo commit object CID. */ commit: CID + /** DEPRECATED -- unused. WARNING -- nullable and optional; stick with optional to ensure golang interoperability. */ prev?: CID | null - /** The rev of the emitted commit. */ + /** The rev of the emitted commit. Note that this information is also in the commit object included in blocks, unless this is a tooBig event. */ rev: string - /** The rev of the last emitted commit from this repo. */ + /** The rev of the last emitted commit from this repo (if any). */ since: string | null - /** CAR file containing relevant blocks. */ + /** CAR file containing relevant blocks, as a diff since the previous repo state. */ blocks: Uint8Array ops: RepoOp[] blobs: CID[] + /** Timestamp of when this message was originally broadcast. */ time: string [k: string]: unknown } @@ -63,6 +71,7 @@ export function validateCommit(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#commit', v) } +/** Represents an update of the account's handle, or transition to/from invalid state. */ export interface Handle { seq: number did: string @@ -83,6 +92,7 @@ export function validateHandle(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#handle', v) } +/** Represents an account moving from one PDS instance to another. NOTE: not implemented; full account migration may introduce a new message instead. */ export interface Migrate { seq: number did: string @@ -103,6 +113,7 @@ export function validateMigrate(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#migrate', v) } +/** Indicates that an account has been deleted. */ export interface Tombstone { seq: number did: string @@ -140,10 +151,11 @@ export function validateInfo(v: unknown): ValidationResult { return lexicons.validate('com.atproto.sync.subscribeRepos#info', v) } -/** A repo operation, ie a write of a single record. For creates and updates, CID is the record's CID as of this operation. For deletes, it's null. */ +/** A repo operation, ie a mutation of a single record. */ export interface RepoOp { action: 'create' | 'update' | 'delete' | (string & {}) path: string + /** For creates and updates, the new record CID. For deletions, null. */ cid: CID | null [k: string]: unknown }