"""
Social Media Profiles
Retrieve information about social media users' profiles.
"""

name = "social-media/profiles"
version = "1.1.0"

"""
Get Profiles by ID
Retrieve information about social media profile
"""
usecase GetProfiles safe {
  input {
    """
    Profile IDs
    A list of profile identifiers to obtain information about
    """
    profileIds! [string!]!
    """
    Page
    Pagination cursor (obtained from `nextPage`)
    """
    page string
  }

  result ResultModel

  error ErrorModel

  example Successful {
    input {
      profileIds = ["783214", "13334762"]
    }

    result {
      profiles = [
        {
          description = "What's happening?!",
          followersCount = 61133560,
          followingCount = 1,
          id = "783214",
          imageUrl = "https://pbs.twimg.com/profile_images/1488548719062654976/u6qfBBkF_normal.jpg",
          postsCount = 14995,
          profileUrl = "https://twitter.com/Twitter",
          username = "Twitter",
          website = "https://t.co/DAtOo6uuHk",
        },
        {
          description = "How people build software.",
          followersCount = 2236837,
          followingCount = 332,
          id = "13334762",
          imageUrl = "https://pbs.twimg.com/profile_images/1414990564408262661/r6YemvF9_normal.jpg",
          postsCount = 6879,
          profileUrl = "https://twitter.com/github",
          username = "github",
        }
      ],
      rateLimit = {
        bucket = "User lookup",
        totalRequests = 15,
        remainingRequests = 12,
        remainingRequestsPercentage = 80,
        resetTimestamp = 1643713585,
      }
    }
  }

  example Failed {
    input {
      profileIds = ["429238130"]
    }

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

"""
Get Profiles by Username
Retrieve information about social media profile
"""
usecase GetProfilesByUsername safe {
  input {
    """
    usernames
    A list of unique usernames to obtain information about profiles
    """
    usernames! [string!]!
    """
    Page
    Pagination cursor (obtained from `nextPage`)
    """
    page string
  }

  result ResultModel

  error ErrorModel

  example Successful {
    input {
      usernames = ["superfaceai", "CrowdDevHQ"]
    }

    result {
      profiles = [
        {
          description = "Low-code API & Edge API Integration. We build the successor to APIs so you can focus on your business and never worry about APIs again.",
          followersCount = 678,
          followingCount = 545,
          id = "1196797704015400960",
          imageUrl = "https://pbs.twimg.com/profile_images/1343506099786412032/WXYqcht6_normal.jpg",
          name = "superface",
          postsCount = 158,
          profileUrl = "https://twitter.com/superfaceai",
          username = "superfaceai",
          website = "https://t.co/1eIDvslNuK",
        },
        {
          description = "Building tools to fuel developer community growth. 
  Join our free beta. 👇",
          followersCount = 101,
          followingCount = 82,
          id = "1362101830923259908",
          imageUrl = "https://pbs.twimg.com/profile_images/1419741008716251141/6exZe94-_normal.jpg",
          location = "🌍 remote",
          name = "Crowd.dev",
          postsCount = 88,
          profileUrl = "https://twitter.com/CrowdDevHQ",
          username = "CrowdDevHQ",
          website = "https://t.co/GRLDhqFWk4",
        },
      ],
      rateLimit = {
        bucket = "User lookup",
        totalRequests = 15,
        remainingRequests = 12,
        remainingRequestsPercentage = 80,
        resetTimestamp = 1643713585,
      }
    }
  }

  example Failed {
    input {
      usernames = ["superfaceai"]
    }

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

model ResultModel {
  """
  Next page
  Next page cursor.
  """
  nextPage string
  """
  Profiles
  List of profiles
  """
  profiles [ Profile ]
  """
  Rate limit
  Rate limit details.
  """
  rateLimit RateLimit
}

model Profile {
  """
  Profile ID
  Identifier of the user profile.
  """
  id! string

  """
  Username
  Username of the profile, typically unique on the site.
  """
  username string

  """
  Name
  Display name of the profile
  """
  name string

  """
  Image URL
  Profile image url.
  """
  imageUrl string

  """
  URL
  Profile URL on the social media site.
  """
  profileUrl string

  """
  Description
  Text of the profile description (bio).
  """
  description string

  """
  Website
  URL specified in the user's profile (e.g. user's homepage).
  """
  website string

  """
  Location
  User-provided location specified in the profile, can be a real place but doesn't have to be.
  """
  location string

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

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

  """
  Posts count
  How many posts has the profile published
  """
  postsCount number
}

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
}