"""
Social Media Followers
List folowers of a social media profile (e.g. Twitter followers).
"""

name = "social-media/followers"
version = "1.2.0"

"""
Get Followers
Retrieve a paginated list of followers for a social media profile.
"""
usecase GetFollowers safe {
  input {
    """
    Profile ID
    Identifier of a profile to retrieve followers from. May be optional with some providers.
    """
    profileId string
    """
    Page
    Pagination cursor (obtained from `previousPage` or `nextPage`).
    """
    page string
  }

  result {
    """
    Previous page
    Previous page cursor.
    """
    previousPage string
    
    """
    Next page
    Next page cursor.
    """
    nextPage string
    
    """
    Followers
    List of followers.
    """
    followers [ {
      """
      Follower ID
      Profile identifier of the follower.
      """
      id string

      """
      Username
      Username of the follower.
      """
      username string

      """
      Image URL
      Follower profile image url.
      """
      imageUrl string

      """
      Followers count
      How many followers does the follower have
      """
      followersCount number

      """
      Following count
      How many profiles is the follower following
      """
      followingCount number

      """
      Posts count
      How many posts has the follower published
      """
      postsCount number
    } ]
    """
    Rate limit
    Rate limit details.
    """
    rateLimit RateLimit
  }

  error {
    """
    Error Title
    A short, human-readable summary of the problem type.
    """
    title!

    """
    Error Detail
    A human-readable explanation specific to this occurrence of the problem.
    """
    detail

    """
    Code
    Error code.
    """
    code! ErrorCode!

    """
    Rate limit
    Rate limit details.
    """
    rateLimit RateLimit
  }

  example Successful {
    input {
      profileId = "429238130"
    }

    result {
      followers = [
        {
          id = "1466796521412771840",
          username = "superface_test",
          imageUrl = "https://pbs.twimg.com/profile_images/1478302204306067462/5BEbrnPO_normal.jpg",
          followersCount = 42,
          followingCount = 3,
          postsCount = 321,
        }
      ],
      nextPage = "QVFIUjc2Y01oQ3F1bHk5WHNzNVVuS2ZAMSEtpdkxmbC1FV09XcGNmTUc4ZAkhrMlBPU19LYkM0dFY4",
      rateLimit = {
        bucket = "get-users-followed-lists",
        totalRequests = 15,
        remainingRequests = 12,
        remainingRequestsPercentage = 80,
        resetTimestamp = 1643713585,
      }
    }
  }

  example Failed {
    input {
      profileId = "429238130"
    }

    error {
      title = 'Rate limit exceeded',
      detail = 'Twitter API resource \'get-users-followed-lists\' reached max requests quota.',
      code = 'RateLimitReached',
      rateLimit = {
        bucket = "get-users-followed-lists",
        totalRequests = 15,
        remainingRequests = 0,
        remainingRequestsPercentage = 0,
        resetTimestamp = 1643713585,
      }
    }
  }
}


model ErrorCode enum {
  """
  Bad request
  The request was invalid or cannot be otherwise served.
  """
  BadRequest
  """
  Not found
  The profileId does not exist.
  """
  NotFound
  """
  Rate limit reached
  Returned when a request cannot be served due to the user or app reached max requests quota.
  """
  RateLimitReached
  """
  Unauthenticated
  There was a problem authenticating your request. Check that you are passing valid access token.
  """
  Unauthenticated
  """
  Unauthorized
  The request is understood, but it has been refused or access is not allowed.
  """
  Unauthorized
  """
  Unknown error
  Returned when an unexpected error occured.
  """
  UnknownError
}

model RateLimit {
  """
  Bucket
  Different parts of API may have different rate limits.
  Bucket identifies to which part of API the rate limits apply.
  """
  bucket string
  """
  Total requests
  Total requests available in the time window.
  """
  totalRequests number
  """
  Remaining requests
  Remaining requests available in the time window.
  """
  remainingRequests number
  """
  Remaining requests available in percents
  Remaining requests available in the time window in percents.
  """
  remainingRequestsPercentage number
  """
  Reset timestamp
  Timestamp when the rate limits will reset (in  Unix Timestamp format). Available only for providers without rolling rate limit window.
  """
  resetTimestamp number
}