From e4f33df4a75c92800d60ef44b524e54fe54dd43c Mon Sep 17 00:00:00 2001 From: bryan newbold Date: Mon, 5 Feb 2024 19:09:09 -0800 Subject: [PATCH] codegen description-only Lexicon updates --- packages/api/src/client/lexicons.ts | 458 +++++++++++++----- .../src/client/types/app/bsky/actor/defs.ts | 1 + .../client/types/app/bsky/actor/getProfile.ts | 1 + .../client/types/app/bsky/actor/profile.ts | 3 + .../client/types/app/bsky/embed/external.ts | 1 + .../src/client/types/app/bsky/embed/images.ts | 4 + .../src/client/types/app/bsky/embed/record.ts | 1 + .../src/client/types/app/bsky/feed/defs.ts | 1 + .../types/app/bsky/feed/getAuthorFeed.ts | 1 + .../types/app/bsky/feed/getFeedGenerator.ts | 3 + .../types/app/bsky/feed/getFeedSkeleton.ts | 1 + .../client/types/app/bsky/feed/getLikes.ts | 2 + .../client/types/app/bsky/feed/getListFeed.ts | 1 + .../types/app/bsky/feed/getPostThread.ts | 3 + .../client/types/app/bsky/feed/getPosts.ts | 1 + .../types/app/bsky/feed/getRepostedBy.ts | 2 + .../client/types/app/bsky/feed/getTimeline.ts | 1 + .../src/client/types/app/bsky/feed/post.ts | 6 +- .../client/types/app/bsky/feed/threadgate.ts | 1 + .../src/client/types/app/bsky/graph/block.ts | 1 + .../client/types/app/bsky/graph/getList.ts | 1 + .../client/types/app/bsky/graph/getLists.ts | 1 + .../types/app/bsky/graph/getRelationships.ts | 2 + .../src/client/types/app/bsky/graph/list.ts | 1 + .../client/types/app/bsky/graph/listblock.ts | 1 + .../client/types/app/bsky/graph/listitem.ts | 2 + .../client/types/app/bsky/richtext/facet.ts | 9 +- .../com/atproto/identity/updateHandle.ts | 1 + .../com/atproto/moderation/createReport.ts | 1 + .../types/com/atproto/repo/applyWrites.ts | 11 +- .../types/com/atproto/repo/createRecord.ts | 8 +- .../types/com/atproto/repo/deleteRecord.ts | 4 +- .../types/com/atproto/repo/describeRepo.ts | 3 + .../types/com/atproto/repo/getRecord.ts | 2 +- .../types/com/atproto/repo/putRecord.ts | 8 +- .../types/com/atproto/server/createAccount.ts | 8 + .../com/atproto/server/createAppPassword.ts | 1 + .../com/atproto/server/describeServer.ts | 3 + .../atproto/server/getAccountInviteCodes.ts | 1 + .../com/atproto/server/reserveSigningKey.ts | 4 +- .../client/types/com/atproto/sync/getBlob.ts | 2 +- .../types/com/atproto/sync/getRecord.ts | 1 + .../client/types/com/atproto/sync/getRepo.ts | 2 +- .../types/com/atproto/sync/listRepos.ts | 1 + .../types/com/atproto/sync/notifyOfUpdate.ts | 2 +- .../types/com/atproto/sync/requestCrawl.ts | 2 +- .../types/com/atproto/sync/subscribeRepos.ts | 20 +- packages/bsky/src/lexicon/lexicons.ts | 458 +++++++++++++----- .../src/lexicon/types/app/bsky/actor/defs.ts | 1 + .../types/app/bsky/actor/getProfile.ts | 1 + .../lexicon/types/app/bsky/actor/profile.ts | 3 + .../lexicon/types/app/bsky/embed/external.ts | 1 + .../lexicon/types/app/bsky/embed/images.ts | 4 + .../lexicon/types/app/bsky/embed/record.ts | 1 + .../src/lexicon/types/app/bsky/feed/defs.ts | 1 + .../types/app/bsky/feed/getAuthorFeed.ts | 1 + .../types/app/bsky/feed/getFeedGenerator.ts | 3 + .../types/app/bsky/feed/getFeedSkeleton.ts | 1 + .../lexicon/types/app/bsky/feed/getLikes.ts | 2 + .../types/app/bsky/feed/getListFeed.ts | 1 + .../types/app/bsky/feed/getPostThread.ts | 3 + .../lexicon/types/app/bsky/feed/getPosts.ts | 1 + .../types/app/bsky/feed/getRepostedBy.ts | 2 + .../types/app/bsky/feed/getTimeline.ts | 1 + .../src/lexicon/types/app/bsky/feed/post.ts | 6 +- .../lexicon/types/app/bsky/feed/threadgate.ts | 1 + .../src/lexicon/types/app/bsky/graph/block.ts | 1 + .../lexicon/types/app/bsky/graph/getList.ts | 1 + .../lexicon/types/app/bsky/graph/getLists.ts | 1 + .../types/app/bsky/graph/getRelationships.ts | 2 + .../src/lexicon/types/app/bsky/graph/list.ts | 1 + .../lexicon/types/app/bsky/graph/listblock.ts | 1 + .../lexicon/types/app/bsky/graph/listitem.ts | 2 + .../lexicon/types/app/bsky/richtext/facet.ts | 9 +- .../com/atproto/identity/updateHandle.ts | 1 + .../com/atproto/label/subscribeLabels.ts | 2 +- .../com/atproto/moderation/createReport.ts | 1 + .../types/com/atproto/repo/applyWrites.ts | 11 +- .../types/com/atproto/repo/createRecord.ts | 8 +- .../types/com/atproto/repo/deleteRecord.ts | 4 +- .../types/com/atproto/repo/describeRepo.ts | 3 + .../types/com/atproto/repo/getRecord.ts | 2 +- .../types/com/atproto/repo/putRecord.ts | 8 +- .../types/com/atproto/server/createAccount.ts | 8 + .../com/atproto/server/createAppPassword.ts | 1 + .../com/atproto/server/describeServer.ts | 3 + .../atproto/server/getAccountInviteCodes.ts | 1 + .../com/atproto/server/reserveSigningKey.ts | 4 +- .../lexicon/types/com/atproto/sync/getBlob.ts | 2 +- .../types/com/atproto/sync/getRecord.ts | 1 + .../lexicon/types/com/atproto/sync/getRepo.ts | 2 +- .../types/com/atproto/sync/listRepos.ts | 1 + .../types/com/atproto/sync/notifyOfUpdate.ts | 2 +- .../types/com/atproto/sync/requestCrawl.ts | 2 +- .../types/com/atproto/sync/subscribeRepos.ts | 22 +- packages/ozone/src/lexicon/lexicons.ts | 458 +++++++++++++----- .../src/lexicon/types/app/bsky/actor/defs.ts | 1 + .../types/app/bsky/actor/getProfile.ts | 1 + .../lexicon/types/app/bsky/actor/profile.ts | 3 + .../lexicon/types/app/bsky/embed/external.ts | 1 + .../lexicon/types/app/bsky/embed/images.ts | 4 + .../lexicon/types/app/bsky/embed/record.ts | 1 + .../src/lexicon/types/app/bsky/feed/defs.ts | 1 + .../types/app/bsky/feed/getAuthorFeed.ts | 1 + .../types/app/bsky/feed/getFeedGenerator.ts | 3 + .../types/app/bsky/feed/getFeedSkeleton.ts | 1 + .../lexicon/types/app/bsky/feed/getLikes.ts | 2 + .../types/app/bsky/feed/getListFeed.ts | 1 + .../types/app/bsky/feed/getPostThread.ts | 3 + .../lexicon/types/app/bsky/feed/getPosts.ts | 1 + .../types/app/bsky/feed/getRepostedBy.ts | 2 + .../types/app/bsky/feed/getTimeline.ts | 1 + .../src/lexicon/types/app/bsky/feed/post.ts | 6 +- .../lexicon/types/app/bsky/feed/threadgate.ts | 1 + .../src/lexicon/types/app/bsky/graph/block.ts | 1 + .../lexicon/types/app/bsky/graph/getList.ts | 1 + .../lexicon/types/app/bsky/graph/getLists.ts | 1 + .../types/app/bsky/graph/getRelationships.ts | 2 + .../src/lexicon/types/app/bsky/graph/list.ts | 1 + .../lexicon/types/app/bsky/graph/listblock.ts | 1 + .../lexicon/types/app/bsky/graph/listitem.ts | 2 + .../lexicon/types/app/bsky/richtext/facet.ts | 9 +- .../com/atproto/identity/updateHandle.ts | 1 + .../com/atproto/label/subscribeLabels.ts | 2 +- .../com/atproto/moderation/createReport.ts | 1 + .../types/com/atproto/repo/applyWrites.ts | 11 +- .../types/com/atproto/repo/createRecord.ts | 8 +- .../types/com/atproto/repo/deleteRecord.ts | 4 +- .../types/com/atproto/repo/describeRepo.ts | 3 + .../types/com/atproto/repo/getRecord.ts | 2 +- .../types/com/atproto/repo/putRecord.ts | 8 +- .../types/com/atproto/server/createAccount.ts | 8 + .../com/atproto/server/createAppPassword.ts | 1 + .../com/atproto/server/describeServer.ts | 3 + .../atproto/server/getAccountInviteCodes.ts | 1 + .../com/atproto/server/reserveSigningKey.ts | 4 +- .../lexicon/types/com/atproto/sync/getBlob.ts | 2 +- .../types/com/atproto/sync/getRecord.ts | 1 + .../lexicon/types/com/atproto/sync/getRepo.ts | 2 +- .../types/com/atproto/sync/listRepos.ts | 1 + .../types/com/atproto/sync/notifyOfUpdate.ts | 2 +- .../types/com/atproto/sync/requestCrawl.ts | 2 +- .../types/com/atproto/sync/subscribeRepos.ts | 22 +- packages/pds/src/lexicon/lexicons.ts | 458 +++++++++++++----- .../src/lexicon/types/app/bsky/actor/defs.ts | 1 + .../types/app/bsky/actor/getProfile.ts | 1 + .../lexicon/types/app/bsky/actor/profile.ts | 3 + .../lexicon/types/app/bsky/embed/external.ts | 1 + .../lexicon/types/app/bsky/embed/images.ts | 4 + .../lexicon/types/app/bsky/embed/record.ts | 1 + .../src/lexicon/types/app/bsky/feed/defs.ts | 1 + .../types/app/bsky/feed/getAuthorFeed.ts | 1 + .../types/app/bsky/feed/getFeedGenerator.ts | 3 + .../types/app/bsky/feed/getFeedSkeleton.ts | 1 + .../lexicon/types/app/bsky/feed/getLikes.ts | 2 + .../types/app/bsky/feed/getListFeed.ts | 1 + .../types/app/bsky/feed/getPostThread.ts | 3 + .../lexicon/types/app/bsky/feed/getPosts.ts | 1 + .../types/app/bsky/feed/getRepostedBy.ts | 2 + .../types/app/bsky/feed/getTimeline.ts | 1 + .../src/lexicon/types/app/bsky/feed/post.ts | 6 +- .../lexicon/types/app/bsky/feed/threadgate.ts | 1 + .../src/lexicon/types/app/bsky/graph/block.ts | 1 + .../lexicon/types/app/bsky/graph/getList.ts | 1 + .../lexicon/types/app/bsky/graph/getLists.ts | 1 + .../types/app/bsky/graph/getRelationships.ts | 2 + .../src/lexicon/types/app/bsky/graph/list.ts | 1 + .../lexicon/types/app/bsky/graph/listblock.ts | 1 + .../lexicon/types/app/bsky/graph/listitem.ts | 2 + .../lexicon/types/app/bsky/richtext/facet.ts | 9 +- .../com/atproto/identity/updateHandle.ts | 1 + .../com/atproto/label/subscribeLabels.ts | 2 +- .../com/atproto/moderation/createReport.ts | 1 + .../types/com/atproto/repo/applyWrites.ts | 11 +- .../types/com/atproto/repo/createRecord.ts | 8 +- .../types/com/atproto/repo/deleteRecord.ts | 4 +- .../types/com/atproto/repo/describeRepo.ts | 3 + .../types/com/atproto/repo/getRecord.ts | 2 +- .../types/com/atproto/repo/putRecord.ts | 8 +- .../types/com/atproto/server/createAccount.ts | 8 + .../com/atproto/server/createAppPassword.ts | 1 + .../com/atproto/server/describeServer.ts | 3 + .../atproto/server/getAccountInviteCodes.ts | 1 + .../com/atproto/server/reserveSigningKey.ts | 4 +- .../lexicon/types/com/atproto/sync/getBlob.ts | 2 +- .../types/com/atproto/sync/getRecord.ts | 1 + .../lexicon/types/com/atproto/sync/getRepo.ts | 2 +- .../types/com/atproto/sync/listRepos.ts | 1 + .../types/com/atproto/sync/notifyOfUpdate.ts | 2 +- .../types/com/atproto/sync/requestCrawl.ts | 2 +- .../types/com/atproto/sync/subscribeRepos.ts | 22 +- 191 files changed, 1770 insertions(+), 622 deletions(-) diff --git a/packages/api/src/client/lexicons.ts b/packages/api/src/client/lexicons.ts index 515098a8f49..8fcf9491077 100644 --- a/packages/api/src/client/lexicons.ts +++ b/packages/api/src/client/lexicons.ts @@ -1912,7 +1912,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 +1946,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 +1957,7 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'The new handle.', }, }, }, @@ -2046,7 +2048,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 +2110,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 +2173,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 +2183,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 +2301,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 +2311,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 +2334,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 +2344,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 +2369,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 +2386,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 +2406,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 +2417,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 +2427,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 +2469,8 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that 'swapCommit' didn't match current repo commit.", }, ], }, @@ -2462,7 +2482,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 +2493,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 +2503,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, swapRecord: { type: 'string', @@ -2513,7 +2535,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 +2569,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 +2582,8 @@ export const schemaDict = { }, handleIsCorrect: { type: 'boolean', + description: + 'Indicates if handle is currently valid (resolves bi-directionally)', }, }, }, @@ -2570,7 +2597,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 +2615,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, cid: { type: 'string', @@ -2626,7 +2654,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 +2741,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 +2753,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 +2763,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 +2780,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 +2844,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 +2909,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 +2922,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 +2941,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 +2961,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 +2978,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 +3028,8 @@ export const schemaDict = { properties: { name: { type: 'string', + description: + 'A short name for the App Password, to help distinguish them.', }, }, }, @@ -3250,7 +3297,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 +3335,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Delete the current session.', + description: 'Delete the current session. Requires auth.', }, }, }, @@ -3298,7 +3346,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 +3355,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 +3399,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 +3411,8 @@ export const schemaDict = { createAvailable: { type: 'boolean', default: true, + description: + "Controls whether any new 'earned' but not 'created' invites should be created.", }, }, }, @@ -3388,7 +3446,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 +3527,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 +3634,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 +3643,7 @@ export const schemaDict = { properties: { did: { type: 'string', - description: 'The did to reserve a new did:key for', + description: 'The DID to reserve a key for.', }, }, }, @@ -3595,7 +3656,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 +3764,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 +3773,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 +3794,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 +3890,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 +3934,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 +3950,7 @@ export const schemaDict = { }, rkey: { type: 'string', + description: 'Record Key', }, commit: { type: 'string', @@ -3906,7 +3972,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 +3984,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 +4001,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 +4055,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 +4102,7 @@ export const schemaDict = { head: { type: 'string', format: 'cid', + description: 'Current repo commit CID', }, rev: { type: 'string', @@ -4048,7 +4118,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 +4128,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 +4142,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 +4153,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 +4167,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 +4196,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 +4222,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 +4268,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 +4277,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 +4314,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 +4337,7 @@ export const schemaDict = { }, tombstone: { type: 'object', + description: 'Indicates that an account has been deleted.', required: ['seq', 'did', 'time'], properties: { seq: { @@ -4270,8 +4368,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 +4381,8 @@ export const schemaDict = { }, cid: { type: 'cid-link', + description: + 'For creates and updates, the new record CID. For deletions, null.', }, }, }, @@ -4324,7 +4423,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 +4539,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 +4613,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 +4745,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', @@ -4815,7 +4916,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 +4944,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 +4953,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Handle or DID of account to fetch profile of.', }, }, }, @@ -4909,7 +5013,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 +5057,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 +5069,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 +5127,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 +5180,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 +5223,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 +5291,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 +5318,8 @@ export const schemaDict = { }, alt: { type: 'string', + description: + 'Alt text description of the image, for accessibility.', }, aspectRatio: { type: 'ref', @@ -5247,12 +5363,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 +5388,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 +5434,7 @@ export const schemaDict = { }, value: { type: 'unknown', + description: 'The record data itself.', }, labels: { type: 'array', @@ -5376,7 +5499,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 +5598,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 +5860,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 +5915,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 +5950,7 @@ export const schemaDict = { }, labels: { type: 'union', + description: 'Self-label values', refs: ['lex:com.atproto.label.defs#selfLabels'], }, createdAt: { @@ -5841,7 +5968,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 +6017,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 +6074,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 +6095,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 +6144,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 +6197,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 +6206,7 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: 'AT-URI of the feed generator record.', }, }, }, @@ -6088,9 +6222,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 +6281,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 +6290,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 +6337,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 +6346,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 +6419,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 +6428,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the list record.', }, limit: { type: 'integer', @@ -6327,7 +6474,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 +6483,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 +6534,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 +6576,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 +6584,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 +6639,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 +6683,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 +6732,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 +6757,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 +6767,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 +6780,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 +6802,8 @@ export const schemaDict = { }, langs: { type: 'array', + description: + 'Indicates human language of post primary text content.', maxLength: 3, items: { type: 'string', @@ -6644,21 +6812,25 @@ 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 non-inline tags describing this post.', 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 +6890,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 +6917,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 +6981,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 +6989,7 @@ export const schemaDict = { post: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the post record.', }, allow: { type: 'array', @@ -6864,7 +7039,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 +7049,7 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'DID of the account to be blocked.', }, createdAt: { type: 'string', @@ -7061,7 +7238,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 +7264,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 +7308,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 +7361,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 +7414,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 +7423,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 +7468,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 +7512,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 +7556,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 +7565,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'The account (actor) to enumerate lists from.', }, limit: { type: 'integer', @@ -7419,7 +7606,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 +7651,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 +7659,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 +7712,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 +7749,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 +7758,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 +7804,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 +7814,7 @@ export const schemaDict = { subject: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the mod list record.', }, createdAt: { type: 'string', @@ -7633,7 +7831,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 +7841,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 +7864,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 +7888,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 +7912,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 +7935,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 +7958,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 +7990,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 +8102,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 +8136,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 +8160,7 @@ export const schemaDict = { defs: { main: { type: 'object', + description: 'Annotation of a sub-string within rich text.', required: ['index', 'features'], properties: { index: { @@ -7973,7 +8182,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 +8194,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 +8206,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 +8220,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..2e58d890b72 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 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..401510f9ef9 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. */ 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/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 515098a8f49..8fcf9491077 100644 --- a/packages/bsky/src/lexicon/lexicons.ts +++ b/packages/bsky/src/lexicon/lexicons.ts @@ -1912,7 +1912,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 +1946,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 +1957,7 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'The new handle.', }, }, }, @@ -2046,7 +2048,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 +2110,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 +2173,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 +2183,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 +2301,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 +2311,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 +2334,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 +2344,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 +2369,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 +2386,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 +2406,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 +2417,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 +2427,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 +2469,8 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that 'swapCommit' didn't match current repo commit.", }, ], }, @@ -2462,7 +2482,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 +2493,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 +2503,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, swapRecord: { type: 'string', @@ -2513,7 +2535,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 +2569,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 +2582,8 @@ export const schemaDict = { }, handleIsCorrect: { type: 'boolean', + description: + 'Indicates if handle is currently valid (resolves bi-directionally)', }, }, }, @@ -2570,7 +2597,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 +2615,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, cid: { type: 'string', @@ -2626,7 +2654,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 +2741,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 +2753,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 +2763,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 +2780,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 +2844,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 +2909,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 +2922,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 +2941,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 +2961,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 +2978,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 +3028,8 @@ export const schemaDict = { properties: { name: { type: 'string', + description: + 'A short name for the App Password, to help distinguish them.', }, }, }, @@ -3250,7 +3297,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 +3335,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Delete the current session.', + description: 'Delete the current session. Requires auth.', }, }, }, @@ -3298,7 +3346,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 +3355,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 +3399,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 +3411,8 @@ export const schemaDict = { createAvailable: { type: 'boolean', default: true, + description: + "Controls whether any new 'earned' but not 'created' invites should be created.", }, }, }, @@ -3388,7 +3446,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 +3527,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 +3634,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 +3643,7 @@ export const schemaDict = { properties: { did: { type: 'string', - description: 'The did to reserve a new did:key for', + description: 'The DID to reserve a key for.', }, }, }, @@ -3595,7 +3656,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 +3764,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 +3773,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 +3794,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 +3890,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 +3934,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 +3950,7 @@ export const schemaDict = { }, rkey: { type: 'string', + description: 'Record Key', }, commit: { type: 'string', @@ -3906,7 +3972,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 +3984,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 +4001,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 +4055,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 +4102,7 @@ export const schemaDict = { head: { type: 'string', format: 'cid', + description: 'Current repo commit CID', }, rev: { type: 'string', @@ -4048,7 +4118,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 +4128,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 +4142,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 +4153,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 +4167,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 +4196,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 +4222,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 +4268,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 +4277,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 +4314,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 +4337,7 @@ export const schemaDict = { }, tombstone: { type: 'object', + description: 'Indicates that an account has been deleted.', required: ['seq', 'did', 'time'], properties: { seq: { @@ -4270,8 +4368,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 +4381,8 @@ export const schemaDict = { }, cid: { type: 'cid-link', + description: + 'For creates and updates, the new record CID. For deletions, null.', }, }, }, @@ -4324,7 +4423,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 +4539,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 +4613,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 +4745,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', @@ -4815,7 +4916,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 +4944,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 +4953,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Handle or DID of account to fetch profile of.', }, }, }, @@ -4909,7 +5013,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 +5057,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 +5069,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 +5127,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 +5180,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 +5223,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 +5291,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 +5318,8 @@ export const schemaDict = { }, alt: { type: 'string', + description: + 'Alt text description of the image, for accessibility.', }, aspectRatio: { type: 'ref', @@ -5247,12 +5363,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 +5388,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 +5434,7 @@ export const schemaDict = { }, value: { type: 'unknown', + description: 'The record data itself.', }, labels: { type: 'array', @@ -5376,7 +5499,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 +5598,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 +5860,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 +5915,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 +5950,7 @@ export const schemaDict = { }, labels: { type: 'union', + description: 'Self-label values', refs: ['lex:com.atproto.label.defs#selfLabels'], }, createdAt: { @@ -5841,7 +5968,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 +6017,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 +6074,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 +6095,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 +6144,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 +6197,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 +6206,7 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: 'AT-URI of the feed generator record.', }, }, }, @@ -6088,9 +6222,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 +6281,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 +6290,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 +6337,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 +6346,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 +6419,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 +6428,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the list record.', }, limit: { type: 'integer', @@ -6327,7 +6474,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 +6483,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 +6534,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 +6576,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 +6584,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 +6639,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 +6683,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 +6732,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 +6757,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 +6767,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 +6780,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 +6802,8 @@ export const schemaDict = { }, langs: { type: 'array', + description: + 'Indicates human language of post primary text content.', maxLength: 3, items: { type: 'string', @@ -6644,21 +6812,25 @@ 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 non-inline tags describing this post.', 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 +6890,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 +6917,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 +6981,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 +6989,7 @@ export const schemaDict = { post: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the post record.', }, allow: { type: 'array', @@ -6864,7 +7039,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 +7049,7 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'DID of the account to be blocked.', }, createdAt: { type: 'string', @@ -7061,7 +7238,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 +7264,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 +7308,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 +7361,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 +7414,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 +7423,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 +7468,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 +7512,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 +7556,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 +7565,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'The account (actor) to enumerate lists from.', }, limit: { type: 'integer', @@ -7419,7 +7606,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 +7651,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 +7659,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 +7712,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 +7749,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 +7758,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 +7804,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 +7814,7 @@ export const schemaDict = { subject: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the mod list record.', }, createdAt: { type: 'string', @@ -7633,7 +7831,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 +7841,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 +7864,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 +7888,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 +7912,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 +7935,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 +7958,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 +7990,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 +8102,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 +8136,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 +8160,7 @@ export const schemaDict = { defs: { main: { type: 'object', + description: 'Annotation of a sub-string within rich text.', required: ['index', 'features'], properties: { index: { @@ -7973,7 +8182,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 +8194,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 +8206,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 +8220,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..ff49c40dc0b 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 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 802afda5361..9e18f750eee 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 } 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 25f51f6fe5f..71229ec5745 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 fab3b30c316..926d23cd241 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 } 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 1c8f349b42b..155d7b8b25a 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 } 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 d581f5bfa9c..e2655188049 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 } 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 e24c3f8ed22..b5b4a408a71 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 } 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 61de94b729d..ee4ae6bcec5 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 } 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 4282f5d349f..0e6213022d4 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 } 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 0b9c1a6f68b..aa2f04114a3 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 } 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 832caf5c6f7..aabb1fa3ebe 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 } 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..c30825e118a 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. */ 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 fc45dd20985..1a60a7b3b9c 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 } 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 8acf9362c00..e6e4b827bfe 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 } 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 32a27434782..e5e3c66d909 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 } 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/identity/updateHandle.ts b/packages/bsky/src/lexicon/types/com/atproto/identity/updateHandle.ts index 1f639c344e9..8bcc1b2c706 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 } 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 96aaf4a9c29..28d032c7919 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 61d1e7c28e4..9bc2a029674 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 } 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 df8c5d9e600..bff151d5fee 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 } 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 f45118a3769..7d4ec8465f6 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 } 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 7b8a2b995eb..68ca2fea713 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 35c9b4b7166..79c10ad0cb7 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 f10f773c1c4..555a094b608 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 } 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 bbf2c009bf5..1937c6d92eb 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 8e4a0a519e0..dd199c5f13a 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 } 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 bb574dba9ff..81804736315 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 e387a5e38e4..4a681e76362 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 ad5a5a8758c..98ecb2013b6 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 } 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 60750902472..87cd2c3e3f9 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 } 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 297f0ac7794..416f5260ae2 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 495d31a1a22..5b0bca40de4 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 } 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 783a8e314c2..8c8b0bb1842 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 3d310c1139a..d518884dd98 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 } 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 87ef20d7297..b35cccc0f8a 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 } 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/ozone/src/lexicon/lexicons.ts b/packages/ozone/src/lexicon/lexicons.ts index 515098a8f49..8fcf9491077 100644 --- a/packages/ozone/src/lexicon/lexicons.ts +++ b/packages/ozone/src/lexicon/lexicons.ts @@ -1912,7 +1912,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 +1946,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 +1957,7 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'The new handle.', }, }, }, @@ -2046,7 +2048,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 +2110,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 +2173,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 +2183,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 +2301,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 +2311,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 +2334,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 +2344,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 +2369,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 +2386,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 +2406,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 +2417,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 +2427,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 +2469,8 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that 'swapCommit' didn't match current repo commit.", }, ], }, @@ -2462,7 +2482,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 +2493,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 +2503,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, swapRecord: { type: 'string', @@ -2513,7 +2535,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 +2569,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 +2582,8 @@ export const schemaDict = { }, handleIsCorrect: { type: 'boolean', + description: + 'Indicates if handle is currently valid (resolves bi-directionally)', }, }, }, @@ -2570,7 +2597,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 +2615,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, cid: { type: 'string', @@ -2626,7 +2654,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 +2741,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 +2753,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 +2763,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 +2780,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 +2844,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 +2909,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 +2922,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 +2941,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 +2961,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 +2978,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 +3028,8 @@ export const schemaDict = { properties: { name: { type: 'string', + description: + 'A short name for the App Password, to help distinguish them.', }, }, }, @@ -3250,7 +3297,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 +3335,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Delete the current session.', + description: 'Delete the current session. Requires auth.', }, }, }, @@ -3298,7 +3346,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 +3355,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 +3399,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 +3411,8 @@ export const schemaDict = { createAvailable: { type: 'boolean', default: true, + description: + "Controls whether any new 'earned' but not 'created' invites should be created.", }, }, }, @@ -3388,7 +3446,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 +3527,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 +3634,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 +3643,7 @@ export const schemaDict = { properties: { did: { type: 'string', - description: 'The did to reserve a new did:key for', + description: 'The DID to reserve a key for.', }, }, }, @@ -3595,7 +3656,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 +3764,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 +3773,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 +3794,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 +3890,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 +3934,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 +3950,7 @@ export const schemaDict = { }, rkey: { type: 'string', + description: 'Record Key', }, commit: { type: 'string', @@ -3906,7 +3972,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 +3984,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 +4001,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 +4055,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 +4102,7 @@ export const schemaDict = { head: { type: 'string', format: 'cid', + description: 'Current repo commit CID', }, rev: { type: 'string', @@ -4048,7 +4118,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 +4128,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 +4142,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 +4153,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 +4167,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 +4196,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 +4222,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 +4268,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 +4277,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 +4314,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 +4337,7 @@ export const schemaDict = { }, tombstone: { type: 'object', + description: 'Indicates that an account has been deleted.', required: ['seq', 'did', 'time'], properties: { seq: { @@ -4270,8 +4368,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 +4381,8 @@ export const schemaDict = { }, cid: { type: 'cid-link', + description: + 'For creates and updates, the new record CID. For deletions, null.', }, }, }, @@ -4324,7 +4423,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 +4539,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 +4613,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 +4745,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', @@ -4815,7 +4916,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 +4944,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 +4953,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Handle or DID of account to fetch profile of.', }, }, }, @@ -4909,7 +5013,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 +5057,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 +5069,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 +5127,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 +5180,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 +5223,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 +5291,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 +5318,8 @@ export const schemaDict = { }, alt: { type: 'string', + description: + 'Alt text description of the image, for accessibility.', }, aspectRatio: { type: 'ref', @@ -5247,12 +5363,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 +5388,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 +5434,7 @@ export const schemaDict = { }, value: { type: 'unknown', + description: 'The record data itself.', }, labels: { type: 'array', @@ -5376,7 +5499,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 +5598,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 +5860,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 +5915,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 +5950,7 @@ export const schemaDict = { }, labels: { type: 'union', + description: 'Self-label values', refs: ['lex:com.atproto.label.defs#selfLabels'], }, createdAt: { @@ -5841,7 +5968,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 +6017,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 +6074,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 +6095,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 +6144,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 +6197,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 +6206,7 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: 'AT-URI of the feed generator record.', }, }, }, @@ -6088,9 +6222,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 +6281,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 +6290,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 +6337,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 +6346,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 +6419,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 +6428,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the list record.', }, limit: { type: 'integer', @@ -6327,7 +6474,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 +6483,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 +6534,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 +6576,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 +6584,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 +6639,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 +6683,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 +6732,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 +6757,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 +6767,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 +6780,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 +6802,8 @@ export const schemaDict = { }, langs: { type: 'array', + description: + 'Indicates human language of post primary text content.', maxLength: 3, items: { type: 'string', @@ -6644,21 +6812,25 @@ 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 non-inline tags describing this post.', 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 +6890,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 +6917,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 +6981,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 +6989,7 @@ export const schemaDict = { post: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the post record.', }, allow: { type: 'array', @@ -6864,7 +7039,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 +7049,7 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'DID of the account to be blocked.', }, createdAt: { type: 'string', @@ -7061,7 +7238,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 +7264,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 +7308,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 +7361,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 +7414,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 +7423,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 +7468,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 +7512,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 +7556,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 +7565,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'The account (actor) to enumerate lists from.', }, limit: { type: 'integer', @@ -7419,7 +7606,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 +7651,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 +7659,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 +7712,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 +7749,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 +7758,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 +7804,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 +7814,7 @@ export const schemaDict = { subject: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the mod list record.', }, createdAt: { type: 'string', @@ -7633,7 +7831,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 +7841,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 +7864,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 +7888,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 +7912,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 +7935,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 +7958,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 +7990,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 +8102,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 +8136,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 +8160,7 @@ export const schemaDict = { defs: { main: { type: 'object', + description: 'Annotation of a sub-string within rich text.', required: ['index', 'features'], properties: { index: { @@ -7973,7 +8182,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 +8194,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 +8206,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 +8220,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/ozone/src/lexicon/types/app/bsky/actor/defs.ts b/packages/ozone/src/lexicon/types/app/bsky/actor/defs.ts index 8cdcafcb72f..ff49c40dc0b 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/actor/defs.ts +++ b/packages/ozone/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 diff --git a/packages/ozone/src/lexicon/types/app/bsky/actor/getProfile.ts b/packages/ozone/src/lexicon/types/app/bsky/actor/getProfile.ts index 802afda5361..9e18f750eee 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/actor/getProfile.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/actor/getProfile.ts @@ -10,6 +10,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/actor/profile.ts b/packages/ozone/src/lexicon/types/app/bsky/actor/profile.ts index 7dbc4c1ccec..8810ce7bed9 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/actor/profile.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/embed/external.ts b/packages/ozone/src/lexicon/types/app/bsky/embed/external.ts index f42a6cfd95c..b137ee4b6f5 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/embed/external.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/embed/images.ts b/packages/ozone/src/lexicon/types/app/bsky/embed/images.ts index 4864fad3dea..96399867a1a 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/embed/images.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/embed/record.ts b/packages/ozone/src/lexicon/types/app/bsky/embed/record.ts index cea5742a45e..dbe7f13152b 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/embed/record.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/feed/defs.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/defs.ts index 382d3f58ecf..261d8a622ec 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/defs.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts index 25f51f6fe5f..71229ec5745 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/getAuthorFeed.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts index fab3b30c316..926d23cd241 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/feed/getFeedGenerator.ts @@ -10,6 +10,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts index 1c8f349b42b..155d7b8b25a 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/feed/getFeedSkeleton.ts @@ -10,6 +10,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/feed/getLikes.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/getLikes.ts index d581f5bfa9c..e2655188049 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/getLikes.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/feed/getLikes.ts @@ -10,7 +10,9 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/feed/getListFeed.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/getListFeed.ts index e24c3f8ed22..b5b4a408a71 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/getListFeed.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/feed/getListFeed.ts @@ -10,6 +10,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/feed/getPostThread.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/getPostThread.ts index 61de94b729d..ee4ae6bcec5 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/getPostThread.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/feed/getPostThread.ts @@ -10,8 +10,11 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/feed/getPosts.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/getPosts.ts index 4282f5d349f..0e6213022d4 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/getPosts.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/feed/getPosts.ts @@ -10,6 +10,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/feed/getRepostedBy.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/getRepostedBy.ts index 0b9c1a6f68b..aa2f04114a3 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/getRepostedBy.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/feed/getRepostedBy.ts @@ -10,7 +10,9 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/feed/getTimeline.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/getTimeline.ts index 832caf5c6f7..aabb1fa3ebe 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/getTimeline.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/feed/getTimeline.ts @@ -10,6 +10,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/feed/post.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/post.ts index 93870b4452d..c30825e118a 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/post.ts +++ b/packages/ozone/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. */ tags?: string[] + /** Client-declared timestamp when this post was originally created. */ createdAt: string [k: string]: unknown } diff --git a/packages/ozone/src/lexicon/types/app/bsky/feed/threadgate.ts b/packages/ozone/src/lexicon/types/app/bsky/feed/threadgate.ts index 6a190d6e98a..e14140d5609 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/feed/threadgate.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/graph/block.ts b/packages/ozone/src/lexicon/types/app/bsky/graph/block.ts index 947463af422..b7f19f126b7 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/graph/block.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/graph/getList.ts b/packages/ozone/src/lexicon/types/app/bsky/graph/getList.ts index fc45dd20985..1a60a7b3b9c 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/graph/getList.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/graph/getList.ts @@ -10,6 +10,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/graph/getLists.ts b/packages/ozone/src/lexicon/types/app/bsky/graph/getLists.ts index 8acf9362c00..e6e4b827bfe 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/graph/getLists.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/graph/getLists.ts @@ -10,6 +10,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/graph/getRelationships.ts b/packages/ozone/src/lexicon/types/app/bsky/graph/getRelationships.ts index 32a27434782..e5e3c66d909 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/graph/getRelationships.ts +++ b/packages/ozone/src/lexicon/types/app/bsky/graph/getRelationships.ts @@ -10,7 +10,9 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/app/bsky/graph/list.ts b/packages/ozone/src/lexicon/types/app/bsky/graph/list.ts index 36a7fb17a3f..91c8ccee5bb 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/graph/list.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/graph/listblock.ts b/packages/ozone/src/lexicon/types/app/bsky/graph/listblock.ts index 59f2e057eb5..592778c7a51 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/graph/listblock.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/graph/listitem.ts b/packages/ozone/src/lexicon/types/app/bsky/graph/listitem.ts index 69eff329ed4..5e93b34a111 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/graph/listitem.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/app/bsky/richtext/facet.ts b/packages/ozone/src/lexicon/types/app/bsky/richtext/facet.ts index 2c5b2d723a9..139b5382caf 100644 --- a/packages/ozone/src/lexicon/types/app/bsky/richtext/facet.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/identity/updateHandle.ts b/packages/ozone/src/lexicon/types/com/atproto/identity/updateHandle.ts index 1f639c344e9..8bcc1b2c706 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/identity/updateHandle.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/identity/updateHandle.ts @@ -11,6 +11,7 @@ import { HandlerAuth } from '@atproto/xrpc-server' export interface QueryParams {} export interface InputSchema { + /** The new handle. */ handle: string [k: string]: unknown } diff --git a/packages/ozone/src/lexicon/types/com/atproto/label/subscribeLabels.ts b/packages/ozone/src/lexicon/types/com/atproto/label/subscribeLabels.ts index 9d4b4441ae0..6034b35d895 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/label/subscribeLabels.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/moderation/createReport.ts b/packages/ozone/src/lexicon/types/com/atproto/moderation/createReport.ts index 96aaf4a9c29..28d032c7919 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/moderation/createReport.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/repo/applyWrites.ts b/packages/ozone/src/lexicon/types/com/atproto/repo/applyWrites.ts index 61d1e7c28e4..9bc2a029674 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/repo/applyWrites.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/repo/applyWrites.ts @@ -11,11 +11,12 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/repo/createRecord.ts b/packages/ozone/src/lexicon/types/com/atproto/repo/createRecord.ts index df8c5d9e600..bff151d5fee 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/repo/createRecord.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/repo/createRecord.ts @@ -11,15 +11,15 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/repo/deleteRecord.ts b/packages/ozone/src/lexicon/types/com/atproto/repo/deleteRecord.ts index f45118a3769..7d4ec8465f6 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/repo/deleteRecord.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/repo/deleteRecord.ts @@ -11,11 +11,11 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/repo/describeRepo.ts b/packages/ozone/src/lexicon/types/com/atproto/repo/describeRepo.ts index 7b8a2b995eb..68ca2fea713 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/repo/describeRepo.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/repo/getRecord.ts b/packages/ozone/src/lexicon/types/com/atproto/repo/getRecord.ts index 35c9b4b7166..79c10ad0cb7 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/repo/getRecord.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/repo/putRecord.ts b/packages/ozone/src/lexicon/types/com/atproto/repo/putRecord.ts index f10f773c1c4..555a094b608 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/repo/putRecord.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/repo/putRecord.ts @@ -11,17 +11,17 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/server/createAccount.ts b/packages/ozone/src/lexicon/types/com/atproto/server/createAccount.ts index bbf2c009bf5..1937c6d92eb 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/server/createAccount.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/server/createAppPassword.ts b/packages/ozone/src/lexicon/types/com/atproto/server/createAppPassword.ts index 8e4a0a519e0..dd199c5f13a 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/server/createAppPassword.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/server/createAppPassword.ts @@ -11,6 +11,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/server/describeServer.ts b/packages/ozone/src/lexicon/types/com/atproto/server/describeServer.ts index bb574dba9ff..81804736315 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/server/describeServer.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts b/packages/ozone/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts index e387a5e38e4..4a681e76362 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/server/getAccountInviteCodes.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/server/reserveSigningKey.ts b/packages/ozone/src/lexicon/types/com/atproto/server/reserveSigningKey.ts index ad5a5a8758c..98ecb2013b6 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/server/reserveSigningKey.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/server/reserveSigningKey.ts @@ -11,13 +11,13 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/sync/getBlob.ts b/packages/ozone/src/lexicon/types/com/atproto/sync/getBlob.ts index 60750902472..87cd2c3e3f9 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/sync/getBlob.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/sync/getBlob.ts @@ -10,7 +10,7 @@ import { CID } from 'multiformats/cid' import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/sync/getRecord.ts b/packages/ozone/src/lexicon/types/com/atproto/sync/getRecord.ts index 297f0ac7794..416f5260ae2 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/sync/getRecord.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/sync/getRepo.ts b/packages/ozone/src/lexicon/types/com/atproto/sync/getRepo.ts index 495d31a1a22..5b0bca40de4 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/sync/getRepo.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/sync/getRepo.ts @@ -12,7 +12,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/sync/listRepos.ts b/packages/ozone/src/lexicon/types/com/atproto/sync/listRepos.ts index 783a8e314c2..8c8b0bb1842 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/sync/listRepos.ts +++ b/packages/ozone/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/ozone/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts b/packages/ozone/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts index 3d310c1139a..d518884dd98 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/sync/notifyOfUpdate.ts @@ -11,7 +11,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/sync/requestCrawl.ts b/packages/ozone/src/lexicon/types/com/atproto/sync/requestCrawl.ts index 87ef20d7297..b35cccc0f8a 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/sync/requestCrawl.ts +++ b/packages/ozone/src/lexicon/types/com/atproto/sync/requestCrawl.ts @@ -11,7 +11,7 @@ import { HandlerAuth } 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/ozone/src/lexicon/types/com/atproto/sync/subscribeRepos.ts b/packages/ozone/src/lexicon/types/com/atproto/sync/subscribeRepos.ts index fb334778bf6..689ea76daee 100644 --- a/packages/ozone/src/lexicon/types/com/atproto/sync/subscribeRepos.ts +++ b/packages/ozone/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 515098a8f49..8fcf9491077 100644 --- a/packages/pds/src/lexicon/lexicons.ts +++ b/packages/pds/src/lexicon/lexicons.ts @@ -1912,7 +1912,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 +1946,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 +1957,7 @@ export const schemaDict = { handle: { type: 'string', format: 'handle', + description: 'The new handle.', }, }, }, @@ -2046,7 +2048,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 +2110,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 +2173,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 +2183,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 +2301,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 +2311,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 +2334,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 +2344,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 +2369,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 +2386,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 +2406,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 +2417,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 +2427,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 +2469,8 @@ export const schemaDict = { errors: [ { name: 'InvalidSwap', + description: + "Indicates that 'swapCommit' didn't match current repo commit.", }, ], }, @@ -2462,7 +2482,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 +2493,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 +2503,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, swapRecord: { type: 'string', @@ -2513,7 +2535,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 +2569,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 +2582,8 @@ export const schemaDict = { }, handleIsCorrect: { type: 'boolean', + description: + 'Indicates if handle is currently valid (resolves bi-directionally)', }, }, }, @@ -2570,7 +2597,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 +2615,7 @@ export const schemaDict = { }, rkey: { type: 'string', - description: 'The key of the record.', + description: 'The Record Key.', }, cid: { type: 'string', @@ -2626,7 +2654,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 +2741,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 +2753,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 +2763,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 +2780,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 +2844,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 +2909,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 +2922,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 +2941,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 +2961,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 +2978,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 +3028,8 @@ export const schemaDict = { properties: { name: { type: 'string', + description: + 'A short name for the App Password, to help distinguish them.', }, }, }, @@ -3250,7 +3297,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 +3335,7 @@ export const schemaDict = { defs: { main: { type: 'procedure', - description: 'Delete the current session.', + description: 'Delete the current session. Requires auth.', }, }, }, @@ -3298,7 +3346,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 +3355,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 +3399,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 +3411,8 @@ export const schemaDict = { createAvailable: { type: 'boolean', default: true, + description: + "Controls whether any new 'earned' but not 'created' invites should be created.", }, }, }, @@ -3388,7 +3446,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 +3527,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 +3634,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 +3643,7 @@ export const schemaDict = { properties: { did: { type: 'string', - description: 'The did to reserve a new did:key for', + description: 'The DID to reserve a key for.', }, }, }, @@ -3595,7 +3656,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 +3764,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 +3773,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 +3794,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 +3890,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 +3934,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 +3950,7 @@ export const schemaDict = { }, rkey: { type: 'string', + description: 'Record Key', }, commit: { type: 'string', @@ -3906,7 +3972,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 +3984,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 +4001,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 +4055,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 +4102,7 @@ export const schemaDict = { head: { type: 'string', format: 'cid', + description: 'Current repo commit CID', }, rev: { type: 'string', @@ -4048,7 +4118,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 +4128,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 +4142,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 +4153,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 +4167,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 +4196,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 +4222,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 +4268,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 +4277,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 +4314,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 +4337,7 @@ export const schemaDict = { }, tombstone: { type: 'object', + description: 'Indicates that an account has been deleted.', required: ['seq', 'did', 'time'], properties: { seq: { @@ -4270,8 +4368,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 +4381,8 @@ export const schemaDict = { }, cid: { type: 'cid-link', + description: + 'For creates and updates, the new record CID. For deletions, null.', }, }, }, @@ -4324,7 +4423,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 +4539,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 +4613,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 +4745,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', @@ -4815,7 +4916,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 +4944,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 +4953,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'Handle or DID of account to fetch profile of.', }, }, }, @@ -4909,7 +5013,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 +5057,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 +5069,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 +5127,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 +5180,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 +5223,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 +5291,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 +5318,8 @@ export const schemaDict = { }, alt: { type: 'string', + description: + 'Alt text description of the image, for accessibility.', }, aspectRatio: { type: 'ref', @@ -5247,12 +5363,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 +5388,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 +5434,7 @@ export const schemaDict = { }, value: { type: 'unknown', + description: 'The record data itself.', }, labels: { type: 'array', @@ -5376,7 +5499,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 +5598,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 +5860,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 +5915,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 +5950,7 @@ export const schemaDict = { }, labels: { type: 'union', + description: 'Self-label values', refs: ['lex:com.atproto.label.defs#selfLabels'], }, createdAt: { @@ -5841,7 +5968,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 +6017,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 +6074,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 +6095,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 +6144,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 +6197,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 +6206,7 @@ export const schemaDict = { feed: { type: 'string', format: 'at-uri', + description: 'AT-URI of the feed generator record.', }, }, }, @@ -6088,9 +6222,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 +6281,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 +6290,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 +6337,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 +6346,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 +6419,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 +6428,7 @@ export const schemaDict = { list: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the list record.', }, limit: { type: 'integer', @@ -6327,7 +6474,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 +6483,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 +6534,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 +6576,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 +6584,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 +6639,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 +6683,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 +6732,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 +6757,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 +6767,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 +6780,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 +6802,8 @@ export const schemaDict = { }, langs: { type: 'array', + description: + 'Indicates human language of post primary text content.', maxLength: 3, items: { type: 'string', @@ -6644,21 +6812,25 @@ 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 non-inline tags describing this post.', 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 +6890,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 +6917,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 +6981,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 +6989,7 @@ export const schemaDict = { post: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the post record.', }, allow: { type: 'array', @@ -6864,7 +7039,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 +7049,7 @@ export const schemaDict = { subject: { type: 'string', format: 'did', + description: 'DID of the account to be blocked.', }, createdAt: { type: 'string', @@ -7061,7 +7238,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 +7264,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 +7308,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 +7361,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 +7414,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 +7423,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 +7468,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 +7512,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 +7556,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 +7565,7 @@ export const schemaDict = { actor: { type: 'string', format: 'at-identifier', + description: 'The account (actor) to enumerate lists from.', }, limit: { type: 'integer', @@ -7419,7 +7606,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 +7651,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 +7659,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 +7712,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 +7749,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 +7758,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 +7804,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 +7814,7 @@ export const schemaDict = { subject: { type: 'string', format: 'at-uri', + description: 'Reference (AT-URI) to the mod list record.', }, createdAt: { type: 'string', @@ -7633,7 +7831,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 +7841,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 +7864,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 +7888,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 +7912,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 +7935,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 +7958,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 +7990,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 +8102,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 +8136,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 +8160,7 @@ export const schemaDict = { defs: { main: { type: 'object', + description: 'Annotation of a sub-string within rich text.', required: ['index', 'features'], properties: { index: { @@ -7973,7 +8182,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 +8194,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 +8206,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 +8220,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..ff49c40dc0b 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 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 802afda5361..9e18f750eee 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 } 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 25f51f6fe5f..71229ec5745 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 fab3b30c316..926d23cd241 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 } 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 1c8f349b42b..155d7b8b25a 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 } 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 d581f5bfa9c..e2655188049 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 } 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 e24c3f8ed22..b5b4a408a71 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 } 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 61de94b729d..ee4ae6bcec5 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 } 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 4282f5d349f..0e6213022d4 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 } 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 0b9c1a6f68b..aa2f04114a3 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 } 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 832caf5c6f7..aabb1fa3ebe 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 } 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..c30825e118a 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. */ 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 fc45dd20985..1a60a7b3b9c 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 } 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 8acf9362c00..e6e4b827bfe 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 } 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 32a27434782..e5e3c66d909 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 } 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/identity/updateHandle.ts b/packages/pds/src/lexicon/types/com/atproto/identity/updateHandle.ts index 1f639c344e9..8bcc1b2c706 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 } 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 96aaf4a9c29..28d032c7919 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 61d1e7c28e4..9bc2a029674 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 } 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 df8c5d9e600..bff151d5fee 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 } 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 f45118a3769..7d4ec8465f6 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 } 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 7b8a2b995eb..68ca2fea713 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 35c9b4b7166..79c10ad0cb7 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 f10f773c1c4..555a094b608 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 } 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 bbf2c009bf5..1937c6d92eb 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 8e4a0a519e0..dd199c5f13a 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 } 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 bb574dba9ff..81804736315 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 e387a5e38e4..4a681e76362 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 ad5a5a8758c..98ecb2013b6 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 } 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 60750902472..87cd2c3e3f9 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 } 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 297f0ac7794..416f5260ae2 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 495d31a1a22..5b0bca40de4 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 } 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 783a8e314c2..8c8b0bb1842 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 3d310c1139a..d518884dd98 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 } 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 87ef20d7297..b35cccc0f8a 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 } 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 }