@atproto/api 0.9.6 → 0.9.7

package/src/client/types/app/bsky/actor/defs.ts

@@ -82,6 +82,7 @@ export function validateProfileViewDetailed(v: unknown): ValidationResult {
   return lexicons.validate('app.bsky.actor.defs#profileViewDetailed', v)
 }
 
+/** Metadata about the requesting account's relationship with the subject account. Only has meaningful content for authed requests. */
 export interface ViewerState {
   muted?: boolean
   mutedByList?: AppBskyGraphDefs.ListViewBasic
@@ -154,6 +155,7 @@ export function validateContentLabelPref(v: unknown): ValidationResult {
 export interface SavedFeedsPref {
   pinned: string[]
   saved: string[]
+  timelineIndex?: number
   [k: string]: unknown
 }
 

package/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
 }
 

package/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

package/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

package/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

package/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?: (

package/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

package/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'

package/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
 }

package/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

package/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

package/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

package/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
 }
 

package/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[]
 }
 

package/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

package/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

package/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
 }

package/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

package/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

package/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

package/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

package/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[]
 }
 

package/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[]

package/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

package/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

package/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

package/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
 }

package/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

package/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

package/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

package/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

package/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
 }

package/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

package/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

package/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
 }

package/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
 }

package/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

package/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
 }
 

package/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
 }

package/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

package/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

package/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
 }
 

package/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

package/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
 }

package/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
 }