SessionConfiguration Rework

Sources/ATProtoKit/APIReference/ATProtoBlueskyAPI/ListRecord/CreateListRecord.swift

@@ -9,4 +9,158 @@ import Foundation
 
 extension ATProtoBluesky {
 
+    /// A convenience method to create a list record to the user account in Bluesky.
+    /// 
+    /// This can be used instead of creating your own method if you wish not to do so.
+    ///
+    /// # Creating a List
+    ///
+    /// After you authenticate into Bluesky, you can create a list by using the `name` and
+    /// `listType` arguments:
+    ///
+    /// ```swift
+    /// do {
+    ///     let listResult = try await atProtoBluesky.createListRecord(
+    ///         named: "Book Authors",
+    ///         ofType: .reference
+    ///     )
+    ///
+    ///     print(listResult)
+    /// } catch {
+    ///     throw error
+    /// }
+    /// ```
+    ///
+    /// You can optionally add a description and avatar image for the list.
+    ///
+    /// - Note: Names can be up to 64 characters long. \
+    /// \
+    /// Descriptions can be up to 300 characters long.\
+    /// \
+    /// List avatar images can be either .jpg or .png and can be up to 1 MB large.
+    ///
+    /// # Types of Lists
+    ///
+    /// There are three types of lists that can be created:
+    /// - Moderation lists: These are lists where the user accounts listed will be muted
+    /// or blocked.
+    /// - Curated lists: These are lists where the user accounts listed are used for curation:
+    /// things like allowlists for interaction or regular feeds.
+    /// - Reference feeds: These are lists where the user accounts listed will be used as a
+    /// reference, such as with a starter pack.
+    ///
+    /// - Parameters:
+    ///   - name: The name of the list.
+    ///   - listType: The list's type.
+    ///   - description: The list's description. Optional. Defaults to `nil`.
+    ///   - listAvatarImage: The avatar image of the list. Optional. Defaults to `nil`.
+    ///   - labels: An array of labels made by the user. Optional. Defaults to `nil`.
+    ///   - creationDate: The date of the post record. Defaults to `Date.now`.
+    ///   - recordKey: The record key of the collection. Optional. Defaults to `nil`.
+    ///   - shouldValidate: Indicates whether the record should be validated. Optional.
+    ///   Defaults to `true`.
+    ///   - swapCommit: Swaps out an operation based on the CID. Optional. Defaults to `nil`.
+    /// - Returns: A strong reference, which contains the newly-created record's URI and CID hash.
+    public func createListRecord(
+        named name: String,
+        ofType listType: ListType,
+        description: String? = nil,
+        listAvatarImage: ATProtoTools.ImageQuery? = nil,
+        labels: ATUnion.ListLabelsUnion? = nil,
+        creationDate: Date = Date(),
+        recordKey: String? = nil,
+        shouldValidate: Bool? = true,
+        swapCommit: String? = nil
+    ) async throws -> ComAtprotoLexicon.Repository.StrongReference {
+        guard let session else {
+            throw ATRequestPrepareError.missingActiveSession
+        }
+
+        guard let sessionURL = session.pdsURL else {
+            throw ATRequestPrepareError.invalidPDS
+        }
+
+        // listPurpose
+        let listPurpose: AppBskyLexicon.Graph.ListPurpose
+        switch listType {
+            case .moderation:
+                listPurpose = .modlist
+            case .curation:
+                listPurpose = .curatelist
+            case .reference:
+                listPurpose = .referencelist
+        }
+
+        // name
+        // Truncate the number of characters to 64.
+        let nameText = name.truncated(toLength: 64)
+
+        // description and descriptionFacets
+        var descriptionText: String? = nil
+        var descriptionFacets: [AppBskyLexicon.RichText.Facet]? = nil
+
+        if let description = description {
+            // Truncate the number of characters to 300.
+            let truncatedDescriptionText = description.truncated(toLength: 300)
+            descriptionText = truncatedDescriptionText
+
+            let facets = await ATFacetParser.parseFacets(from: truncatedDescriptionText, pdsURL: session.pdsURL ?? "https://bsky.social")
+            descriptionFacets = facets
+        }
+
+        // listAvatarImage
+        var avatarImage: ComAtprotoLexicon.Repository.UploadBlobOutput? = nil
+        if let listAvatarImage = listAvatarImage {
+            let postEmbed = try await uploadImages(
+                [listAvatarImage],
+                pdsURL: sessionURL,
+                accessToken: session.accessToken
+            )
+
+            switch postEmbed {
+                case .images(let imagesDefinition):
+                    let avatarImageContainer = imagesDefinition
+                    avatarImage = avatarImageContainer.images[0].imageBlob
+                default:
+                    break
+            }
+        }
+
+        let listRecord = AppBskyLexicon.Graph.ListRecord(
+            purpose: listPurpose,
+            name: nameText,
+            description: descriptionText,
+            descriptionFacets: descriptionFacets,
+            avatarImageBlob: avatarImage,
+            labels: labels,
+            createdAt: creationDate
+        )
+
+        do {
+            return try await atProtoKitInstance.createRecord(
+                repositoryDID: session.sessionDID,
+                collection: "app.bsky.graph.list",
+                recordKey: recordKey ?? nil,
+                shouldValidate: shouldValidate,
+                record: UnknownType.record(listRecord),
+                swapCommit: swapCommit ?? nil
+            )
+        } catch {
+            throw error
+        }
+    }
+
+    /// The list's type.
+    public enum ListType {
+
+        /// Indicates the list is used for muting or blocking the list of user accounts.
+        case moderation
+
+        /// Indicates the list is used for curation purposes, such as list feeds or
+        /// interaction gating.
+        case curation
+
+        /// Indicates the list is used for reference purposes (such as within a starter pack).
+        case reference
+    }
 }

Sources/ATProtoKit/APIReference/ATProtoBlueskyAPI/ListRecord/DeleteListRecord.swift

@@ -9,4 +9,14 @@ import Foundation
 
 extension ATProtoBluesky {
 
+    /// Deletes a list record.
+    ///
+    /// This can also be used to validate if a list record has been deleted.
+    ///
+    /// - Note: This can be either the URI of the list record, or the full record object itself.
+    ///
+    /// - Parameter record: The list record that needs to be deleted.
+    public func deleteListRecord(_ record: RecordIdentifier) async throws {
+        return try await deleteLikeRecord(record)
+    }
 }

Sources/ATProtoKit/APIReference/ATProtoBlueskyAPI/ListRecord/UpdateListRecord.swift

@@ -0,0 +1,118 @@
+//
+//  UpdateListRecord.swift
+//
+//
+//  Created by Christopher Jr Riley on 2025-02-28.
+//
+
+import Foundation
+
+extension ATProtoBluesky {
+
+    /// A convenience method to update a list record to the user account in Bluesky.
+    /// 
+    /// This can be used instead of creating your own method if you wish not to do so.
+    /// 
+    /// - Parameters:
+    ///   - listURI: The URI of the post.
+    ///   - name: The name of the list.
+    ///   - listType: The list's type.
+    ///   - description: The list's description. Optional. Defaults to `nil`.
+    ///   - listAvatarImage: The avatar image of the list. Optional. Defaults to `nil`.
+    ///   - labels: An array of labels made by the user. Optional. Defaults to `nil`.
+    /// - Returns: A strong reference, which contains the newly-created record's URI and CID hash.
+    public func updateListRecord(
+        listURI: String,
+        name: String,
+        listType: ListType,
+        description: String? = nil,
+        listAvatarImage: ATProtoTools.ImageQuery? = nil,
+        labels: ATUnion.ListLabelsUnion? = nil
+    ) async throws -> ComAtprotoLexicon.Repository.StrongReference {
+        guard let session else {
+            throw ATRequestPrepareError.missingActiveSession
+        }
+
+        guard let sessionURL = session.pdsURL else {
+            throw ATRequestPrepareError.invalidPDS
+        }
+
+        // listPurpose
+        let listPurpose: AppBskyLexicon.Graph.ListPurpose
+        switch listType {
+            case .moderation:
+                listPurpose = .modlist
+            case .curation:
+                listPurpose = .curatelist
+            case .reference:
+                listPurpose = .referencelist
+        }
+
+        // name
+        // Truncate the number of characters to 64.
+        let nameText = name.truncated(toLength: 64)
+
+        // description and descriptionFacets
+        var descriptionText: String? = nil
+        var descriptionFacets: [AppBskyLexicon.RichText.Facet]? = nil
+
+        if let description = description {
+            // Truncate the number of characters to 300.
+            let truncatedDescriptionText = description.truncated(toLength: 300)
+            descriptionText = truncatedDescriptionText
+
+            let facets = await ATFacetParser.parseFacets(from: truncatedDescriptionText, pdsURL: session.pdsURL ?? "https://bsky.social")
+            descriptionFacets = facets
+        }
+
+        // listAvatarImage
+        var postEmbed: ATUnion.PostEmbedUnion? = nil
+        var avatarImage: ComAtprotoLexicon.Repository.UploadBlobOutput? = nil
+        if let listAvatarImage = listAvatarImage {
+            postEmbed = try await uploadImages(
+                [listAvatarImage],
+                pdsURL: sessionURL,
+                accessToken: session.accessToken
+            )
+
+            switch postEmbed {
+                case .images(let imagesDefinition):
+                    let avatarImageContainer = imagesDefinition
+                    avatarImage = avatarImageContainer.images[0].imageBlob
+                default:
+                    break
+            }
+        }
+
+        let listRecord = AppBskyLexicon.Graph.ListRecord(
+            purpose: listPurpose,
+            name: nameText,
+            description: descriptionText,
+            descriptionFacets: descriptionFacets,
+            avatarImageBlob: avatarImage,
+            labels: labels,
+            createdAt: Date()
+        )
+
+        do {
+            let uri = try ATProtoTools().parseURI(listURI)
+
+            guard try await atProtoKitInstance.getRepositoryRecord(
+                from: uri.repository,
+                collection: uri.collection,
+                recordKey: uri.recordKey
+            ).value != nil else {
+                throw ATProtoBlueskyError.postNotFound(message: "List record (\(listURI)) not found.")
+            }
+
+            return try await atProtoKitInstance.putRecord(
+                repository: session.sessionDID,
+                collection: "app.bsky.graph.list",
+                recordKey: uri.recordKey,
+                record: UnknownType.record(listRecord)
+            )
+        } catch {
+            throw error
+        }
+    }
+}

Sources/ATProtoKit/APIReference/ATProtoBlueskyAPI/PostRecord/CreatePostRecord.swift

@@ -13,8 +13,8 @@ extension ATProtoBluesky {
     ///
     /// This can be used instead of creating your own method if you wish not to do so.
     ///
-    /// ## Creating a Post
-    /// After you authenticate into Bluesky, you can create a post by using the `text` field:
+    /// # Creating a Post
+    /// After you authenticate into Bluesky, you can create a post by using the `text` argument:
     /// ```swift
     /// do {
     ///     let postResult = try await atProtoBluesky.createPostRecord(
@@ -68,11 +68,11 @@ extension ATProtoBluesky {
     /// - Note: `startPostion` and `endPostion` must be UTF-8 values.
     ///
     ///
-    /// ## Adding Embedded Content
+    /// # Adding Embedded Content
     /// You can embed various kinds of content in your post, from media to external links,
     /// to other records.
     ///
-    /// ### Images
+    /// ## Images
     /// Use ``ATProtoTools/ImageQuery`` to add details to the image, such as
     /// alt text, then attach it to the post record.
     ///
@@ -81,7 +81,7 @@ extension ATProtoBluesky {
     ///     let image = ATProtoTools.ImageQuery(
     ///         imageData: Data(contentsOf: "/path/to/file/cat.jpg"),
     ///         fileName: "cat.jpg",
-    ///         altText: "A cat looking annoyed, waring a hat."
+    ///         altText: "A cat looking annoyed, wearing a hat."
     ///     )
     ///
     ///     let postResult = try await atProtoBluesky.createPostRecord(
@@ -99,7 +99,7 @@ extension ATProtoBluesky {
     ///
     /// Up to four images can be attached to a post. All images need to be a .jpg format.
     ///
-    /// ### Videos
+    /// ## Videos
     /// Similar to images, you can add videos to a post.
     ///
     /// ```swift
@@ -121,7 +121,7 @@ extension ATProtoBluesky {
     /// You can upload up to 25 videos per day and the 25 videos can't exceed a total of 500 MB
     /// for the day.
     ///
-    /// ### External Links
+    /// ## External Links
     /// You can attach a website card to the post.
     ///
     /// ```swift
@@ -159,7 +159,7 @@ extension ATProtoBluesky {
     /// If there are any links in the post's text, the method will not convert it into a
     /// website card; you will need to manually achieve this.
     ///
-    /// ## Creating a Quote Post
+    /// # Creating a Quote Post
     /// Quote posts are also embeds: you simply need to embed the record's strong reference to it.
     ///
     /// ```swift
@@ -180,7 +180,7 @@ extension ATProtoBluesky {
     /// Only one record can be embedded. This isn't limited to post records, though: you can embed
     /// any Bluesky-related record that you wish.
     ///
-    /// ## Creating a Reply
+    /// # Creating a Reply
     /// To create a reply, pass the reply reference of the post's reply reference to the post record.
     ///
     /// ```swift

Sources/ATProtoKit/APIReference/ATProtoBlueskyAPI/PostgateRecord/CreatePostgateRecord.swift

@@ -37,7 +37,7 @@ extension ATProtoBluesky {
     /// }
     /// ```
     ///
-    /// ## Managing Embedding Post Options
+    /// # Managing Embedding Post Options
     ///
     /// You can detact the post from quote posts by using the `detachedEmbeddingURIs` argument.
     /// When doing so, Bluesky will display a "Removed by author" warning and the quote post will