"""
Lookup Social Media Posts
Retrieve social media posts by hashtag or mention of a profile.
"""

name = "social-media/posts-lookup"
version = "1.3.0"

"""
Lookup Posts by Hashtag
Retrieve recent posts that match a hashtag.
"""
usecase FindByHashtag safe {
  input {
    hashtag string
    afterDate string
    page string
  } 

  result {
    previousPage string
    nextPage string
    posts [Post]
    rateLimit RateLimit
  }

  error Error

  example Successful {
    input {
      hashtag = "apis"
    }

    result {
      posts = [{
          id = "1234567",
          createdAt = "2022-02-02T08:20:04.000Z",
          text = "API stands for Application Programming Interface #apis",
          url = "https://twitter.com/i/status/1234567",
          attachments = [{
              type = "photo",
              url = "https://pbs.twimg.com/media/FKk9-wpWUAEQ-Xs.jpg",
              height = 360,
              width = 480,
            },
          ],
          author = {
            id = "3333333",
            username = "johndoe",
            followersCount = 42,
            followingCount = 3,
            postsCount = 321,
          }
        }
      ],
      nextPage = "QVFIUjc2Y01oQ3F1bHk5WHNzNVVuS2ZAMSEtpdkxmbC1FV09XcGNmTUc4ZAkhrMlBPU19LYkM0dFY4",
      rateLimit = {
        bucket = "Search recent tweets",
        totalRequests = 15,
        remainingRequests = 12,
        remainingRequestsPercentage = 80,
        resetTimestamp = 1643713585,
      }
    }
  }

  example Failed {
    input {
      hashtag = "apis"
    }

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

"""
Lookup Posts by Mention
Retrieve recent posts that mention a social media profile.
"""
usecase FindByMention safe {
  input {
    """
    Profile ID
    The ID of the profile mentioned in the posts.
    """
    profileId string
    afterDate string
    page string
  } 

  result {
    previousPage string
    nextPage string
    posts [Post]
    rateLimit RateLimit
  }

  error Error

  example Successful {
    input {
      profileId = "1111111"
    }

    result {
      posts = [{
          id = "1234567",
          createdAt = "2022-02-02T08:20:04.000Z",
          text = "API stands for Application Programming Interface @superface_test",
          url = "https://twitter.com/i/status/1234567",
          attachments = [{
              type = "photo",
              url = "https://pbs.twimg.com/media/FKk9-wpWUAEQ-Xs.jpg",
              height = 360,
              width = 480,
            },
          ],
          replyId = "222222",
          parentId = "222222",
          author = {
            id = "3333333",
            username = "johndoe",
            followersCount = 42,
            followingCount = 3,
            postsCount = 321,
          }
        }
      ],
      nextPage = "QVFIUjc2Y01oQ3F1bHk5WHNzNVVuS2ZAMSEtpdkxmbC1FV09XcGNmTUc4ZAkhrMlBPU19LYkM0dFY4",
      rateLimit = {
        bucket = "User mention timeline",
        totalRequests = 15,
        remainingRequests = 12,
        remainingRequestsPercentage = 80,
        resetTimestamp = 1643713585,
      }
    }
  }

  example Failed {
    input {
      profileId = "111111"
    }

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

model Post {
  """
  ID
  Identifier of the post.
  """
  id string
  """
  URL
  Permanent URL of the post.
  """
  url string
  """
  Created at
  Date and time the post was published at.
  """
  createdAt string
  """
  Text
  Text of the post.
  """
  text string

  """
  Reply ID
  [DEPRECATED] Use parentId.
  ID of a parent post in case the post is a reply.
  """
  replyId string

  """
  Parent ID
  ID of a parent post in case the post is a reply.
  """
  parentId string

  """
  Author
  The author of the post
  """
  author {
    """
    User ID
    """
    id string
    """
    Username
    """
    username string

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

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

    """
    Posts count
    How many posts has the author published
    """
    postsCount number
  }
  """
  Attachments
  Sequential list of attachments.
  """
  attachments [ {
    """
    Type
    Attachment type.
    """
    type string
    """
    URL
    Attachment URL.
    """
    url string
    """
    Preview URL
    Thumbnail or another preview of the attachment.
    """
    preview
    """
    Title
    Attachment title.
    """
    title string
    """
    Description
    Attachment description.
    """
    description string
    """
    Alternative text
    Alternative text of the attachment.
    """
    altText string
    """
    Duration
    Duration of the attached video.
    """
    duration number
    """
    Width
    Widht of the attached image.
    """
    width number
    """
    Height
    Height of the attached image.
    """
    height number
    }
  ]
}

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

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

  """
  Code
  Machine processable error code.
  """
  code! ErrorCode!

  rateLimit RateLimit
}

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
}

"""
Hashtag
The hashtag with which posts will be filtered.
"""
field hashtag

"""
After date
Filter posts that have been created after the date in ISO 8601 date and time format.
"""
field afterDate

"""
Page
Token of the page to retrieve.
"""
field page

"""
Previous page
Previous page token.
"""
field previousPage

"""
Next page
Next page token.
"""
field nextPage

"""
Posts
List of posts ordered by creation date. Latest posts are on the top of the list.
"""
field posts
"""
Rate limit
Rate limit details.
"""
field rateLimit