Use currently-authenticated user ID for convenience

Author: daneden

Sources/Twift+Blocks.swift

@@ -7,18 +7,20 @@ extension Twift {
   ///
   /// Equivalent to `GET /2/users/:id/blocking`.
   /// - Parameters:
-  ///   - userId: The user ID whose blocked users you would like to retrieve
+  ///   - userId: The user ID whose blocked users you would like to retrieve. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
   ///   - maxResults: The maximum number of results to fetch.
   /// - Returns: A Twitter API response object containing an array of ``User`` structs and any pinned tweets in the `includes` property
-  public func getBlockedUsers(for userId: User.ID,
+  public func getBlockedUsers(for userId: User.ID? = nil,
                               fields: Set<User.Field> = [],
                               expansions: [User.Expansions] = [],
                               paginationToken: String? = nil,
                               maxResults: Int = 100
   ) async throws -> TwitterAPIDataIncludesAndMeta<[User], User.Includes, Meta> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+
     switch maxResults {
     case 0...1000:
       break
@@ -46,7 +48,9 @@ extension Twift {
   ///   - sourceUserId: The user ID who you would like to initiate the block on behalf of. It must match the user ID of the currently authenticated user.
   ///   - targetUserId: The user ID of the user you would like the source user to block.
   /// - Returns: A ``BlockResponse`` indicating the blocked status.
-  public func blockUser(sourceUserId: User.ID, targetUserId: User.ID) async throws -> TwitterAPIData<BlockResponse> {
+  public func blockUser(sourceUserId: User.ID? = nil, targetUserId: User.ID) async throws -> TwitterAPIData<BlockResponse> {
+    guard let sourceUserId = sourceUserId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     let body = ["target_user_id": targetUserId]
     let serializedBody = try JSONSerialization.data(withJSONObject: body)
     return try await call(route: .blocking(sourceUserId),

Sources/Twift+Errors.swift

@@ -15,6 +15,9 @@ public enum TwiftError: Error {
   /// This error is thrown when the called function expected an integer within a specified range but was passed a value outside that range.
   case RangeOutOfBoundsError(min: Int = 1, max: Int = 1000, fieldName: String, actual: Int)
 
+  /// This error is thrown when the function called expects a User ID but the caller did not provide one and one could not be found in the current Twift instance.
+  case MissingUserID
+  
   /// The human-readable description for the error
   public var description: String {
     switch self {
@@ -26,6 +29,8 @@ public enum TwiftError: Error {
       return "Unknown Error"
     case .RangeOutOfBoundsError(let min, let max, let fieldName, let actual):
       return "Expected a value between \(min) and \(max) for field \"\(fieldName)\" but got \(actual)"
+    case .MissingUserID:
+      return "The function called expects a User ID but the caller did not provide one, and one could not be found in the current Twift instance."
     }
   }
 }

Sources/Twift+Follows.swift

@@ -20,12 +20,14 @@ extension Twift {
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
   ///   - maxResults: The maximum number of results to fetch.
   /// - Returns: A Twitter API response object containing an array of ``User`` structs and any pinned tweets in the `includes` property
-  public func getFollowing(_ userId: User.ID,
+  public func getFollowing(_ userId: User.ID? = nil,
                            fields: Set<User.Field> = [],
                            expansions: [User.Expansions] = [],
                            paginationToken: String? = nil,
                            maxResults: Int = 100
   ) async throws -> TwitterAPIDataIncludesAndMeta<[User], User.Includes, Meta> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     switch maxResults {
     case 0...1000:
       break
@@ -55,12 +57,14 @@ extension Twift {
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
   ///   - maxResults: The maximum number of results to fetch.
   /// - Returns: A Twitter API response object containing an array of ``User`` structs and any pinned tweets in the `includes` property
-  public func getFollowers(_ userId: User.ID,
+  public func getFollowers(_ userId: User.ID? = nil,
                            fields: Set<User.Field> = [],
                            expansions: [User.Expansions] = [],
                            paginationToken: String? = nil,
                            maxResults: Int = 100
   ) async throws -> TwitterAPIDataIncludesAndMeta<[User], User.Includes, Meta> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     switch maxResults {
     case 0...1000:
       break
@@ -93,9 +97,10 @@ extension Twift {
   ///   - targetUserId: The user ID of the user that you would like the `sourceUserId` to follow.
   /// - Returns: A ``FollowResponse`` indicating whether the source user is now following the target user, and whether the follow request is pending
   public func followUser(
-    sourceUserId: User.ID,
+    sourceUserId: User.ID? = nil,
     targetUserId: User.ID
   ) async throws -> TwitterAPIData<FollowResponse> {
+    guard let sourceUserId = sourceUserId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
     let body = ["target_user_id": targetUserId]
     let serializedBody = try JSONSerialization.data(withJSONObject: body)
     return try await call(route: .following(sourceUserId),
@@ -113,9 +118,10 @@ extension Twift {
   ///   - sourceUserId: The authenticated user ID who you would like to initiate the unfollow on behalf of.
   ///   - targetUserId: The user ID of the user that you would like the `sourceUserId` to unfollow.
   /// - Returns: A ``FollowResponse`` indicating whether the source user is now following the target user
-  public func unfollowUser(sourceUserId: User.ID,
+  public func unfollowUser(sourceUserId: User.ID? = nil,
                            targetUserId: User.ID
   ) async throws -> TwitterAPIData<FollowResponse> {
+    guard let sourceUserId = sourceUserId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
     return try await call(route: .deleteFollow(sourceUserId: sourceUserId, targetUserId: targetUserId),
                           method: .DELETE,
                           expectedReturnType: TwitterAPIData.self)

Sources/Twift+Likes.swift

@@ -8,7 +8,9 @@ extension Twift {
   ///   - tweetId: The ID of the Tweet that you would like the `userId` to Like.
   ///   - userId: The user ID who you are liking a Tweet on behalf of. It must match your own user ID or that of an authenticating user.
   /// - Returns: A response object containing a ``LikeResponse``
-  public func likeTweet(_ tweetId: Tweet.ID, userId: User.ID) async throws -> TwitterAPIData<LikeResponse> {
+  public func likeTweet(_ tweetId: Tweet.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<LikeResponse> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     let body = ["tweet_id": tweetId]
     let encodedBody = try JSONSerialization.data(withJSONObject: body, options: [])
 
@@ -25,7 +27,9 @@ extension Twift {
   ///   - tweetId: The ID of the Tweet that you would like the `userId` to unlike.
   ///   - userId: The user ID who you are removing Like of a Tweet on behalf of. It must match your own user ID or that of an authenticating user.
   /// - Returns: A response object containing a ``LikeResponse``
-  public func unlikeTweet(_ tweetId: Tweet.ID, userId: User.ID) async throws -> TwitterAPIData<LikeResponse> {
+  public func unlikeTweet(_ tweetId: Tweet.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<LikeResponse> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     return try await call(route: .deleteUserLikes(userId, tweetId: tweetId),
                           method: .DELETE,
                           expectedReturnType: TwitterAPIData.self)
@@ -61,12 +65,14 @@ extension Twift {
   ///   - paginationToken: This parameter is used to move forwards or backwards through 'pages' of results, based on the value of the next_token or previous_token in the response.
   ///   - maxResults: Specifies the number of Tweets to try and retrieve, up to a maximum of 100 per distinct request. By default, 10 results are returned if this parameter is not supplied. The minimum permitted value is 10. It is possible to receive less than the max_results per request throughout the pagination process.
   /// - Returns: A response object containing an array of Tweets liked by the target User
-  public func getLikedTweets(for userId: User.ID,
-                      fields: Set<Tweet.Field> = [],
-                      expansions: [Tweet.Expansions],
-                      paginationToken: String? = nil,
-                      maxResults: Int = 10
+  public func getLikedTweets(for userId: User.ID? = nil,
+                             fields: Set<Tweet.Field> = [],
+                             expansions: [Tweet.Expansions],
+                             paginationToken: String? = nil,
+                             maxResults: Int = 10
   ) async throws -> TwitterAPIDataAndIncludes<[Tweet], Tweet.Includes> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     switch maxResults {
     case 10...100:
       break

Sources/Twift+Lists.swift

@@ -14,10 +14,10 @@ extension Twift {
   ///   - maxResults: The maximum number of results to fetch.
   /// - Returns: A response object containing an array of Tweets, included expansions, and meta data for pagination
   public func getListTweets(_ listId: List.ID,
-                         fields: Set<Tweet.Field>,
-                         expansions: [Tweet.Expansions],
-                         paginationToken: String? = nil,
-                         maxResults: Int = 100
+                            fields: Set<Tweet.Field>,
+                            expansions: [Tweet.Expansions],
+                            paginationToken: String? = nil,
+                            maxResults: Int = 100
   ) async throws -> TwitterAPIDataIncludesAndMeta<[Tweet], Tweet.Includes, Meta> {
     switch maxResults {
     case 1...100:
@@ -68,12 +68,14 @@ extension Twift {
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
   ///   - maxResults: The maximum number of results to fetch.
   /// - Returns: A response object containing an array of Lists owned by the user id, any requested expansions, and a meta object with pagination tokens
-  public func getUserOwnedLists(_ userId: User.ID,
+  public func getUserOwnedLists(_ userId: User.ID? = nil,
                                 fields: Set<List.Field>,
                                 expansions: [List.Expansions],
                                 paginationToken: String?,
                                 maxResults: Int = 100
   ) async throws -> TwitterAPIDataIncludesAndMeta<[List], List.Includes, Meta> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     switch maxResults {
     case 1...100:
       break
@@ -116,12 +118,14 @@ extension Twift {
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
   ///   - maxResults: The maximum number of results to fetch.
   /// - Returns: A response object containing an array of Lists the user is a member of, any expanded objects, and a meta object with pagination tokens.
-  public func getListMemberships(for userId: User.ID,
+  public func getListMemberships(for userId: User.ID? = nil,
                                  fields: Set<List.Field>,
                                  expansions: [List.Expansions],
                                  paginationToken: String?,
                                  maxResults: Int = 100
   ) async throws -> TwitterAPIDataIncludesAndMeta<[List], List.Includes, Meta> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     switch maxResults {
     case 1...100:
       break
@@ -216,7 +220,9 @@ extension Twift {
   ///   - listId: The ID of the List that you would like the user id to unfollow.
   ///   - userId: The user ID who you are unfollowing a List on behalf of. It must match your own user ID or that of an authenticating user
   /// - Returns: A response object containing the result of the unfollow request
-  public func unfollowList(_ listId: List.ID, userId: User.ID) async throws -> TwitterAPIData<FollowResponse> {
+  public func unfollowList(_ listId: List.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<FollowResponse> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     return try await call(route: .userFollowingLists(userId, listId: listId),
                           method: .DELETE,
                           expectedReturnType: TwitterAPIData.self)
@@ -227,7 +233,9 @@ extension Twift {
   ///   - listId: The ID of the List that you would like the user id to follow.
   ///   - userId: The user ID who you are following a List on behalf of. It must match your own user ID or that of an authenticating user
   /// - Returns: A response object containing the result of the follow request
-  public func followList(_ listId: List.ID, userId: User.ID) async throws -> TwitterAPIData<FollowResponse> {
+  public func followList(_ listId: List.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<FollowResponse> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     return try await call(route: .userFollowingLists(userId),
                           method: .POST,
                           expectedReturnType: TwitterAPIData.self)
@@ -275,12 +283,14 @@ extension Twift {
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
   ///   - maxResults: The maximum number of results to fetch.
   /// - Returns: A response object containing an array of lists followed by the user, any requested expansions, and a meta object with pagination information
-  public func getFollowedLists(_ userId: User.ID,
+  public func getFollowedLists(_ userId: User.ID? = nil,
                                fields: Set<List.Field> = [],
                                expansions: [List.Expansions],
                                paginationToken: String? = nil,
                                maxResults: Int = 100
   ) async throws -> TwitterAPIDataIncludesAndMeta<[List], List.Includes, Meta> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     switch maxResults {
     case 1...100:
       break
@@ -311,7 +321,9 @@ extension Twift {
   ///   - listId: The ID of the List that you would like the user id to pin.
   ///   - userId: The user ID who you are pinning a List on behalf of. It must match your own user ID or that of an authenticating user
   /// - Returns: A response object containing the result of this pin list request
-  public func pinList(_ listId: List.ID, userId: User.ID) async throws -> TwitterAPIData<PinnedResponse> {
+  public func pinList(_ listId: List.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<PinnedResponse> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     let body = ["list_id": listId]
     let serializedBody = try JSONSerialization.data(withJSONObject: body)
     return try await call(route: .userPinnedLists(userId),
@@ -327,7 +339,9 @@ extension Twift {
   ///   - listId: The ID of the List that you would like the user id to unpin.
   ///   - userId: The user ID who you are unpinning a List on behalf of. It must match your own user ID or that of an authenticating user
   /// - Returns: A response object containing the result of this unpin list request
-  public func unpinList(_ listId: List.ID, userId: User.ID) async throws -> TwitterAPIData<PinnedResponse> {
+  public func unpinList(_ listId: List.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<PinnedResponse> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     return try await call(route: .userPinnedLists(userId, listId: listId),
                           method: .DELETE,
                           expectedReturnType: TwitterAPIData.self)
@@ -339,10 +353,12 @@ extension Twift {
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   /// - Returns: A response object containing an array of lists pinned by the user, any requested expansions, and a meta object with pagination information
-  public func getPinnedLists(_ userId: User.ID,
+  public func getPinnedLists(_ userId: User.ID? = nil,
                                fields: Set<List.Field> = [],
                                expansions: [List.Expansions]
   ) async throws -> TwitterAPIDataAndIncludes<[List], List.Includes> {
+    guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
+    
     return try await call(route: .userPinnedLists(userId),
                           method: .GET,
                           queryItems: fieldsAndExpansions(for: List.self, fields: fields, expansions: expansions),