"""
Retrieves a single user by their unique identifier.
Throws a 404 error if the user doesn't exist.

Example:
  query {
    user(id: "usr_123") {
      email
      posts {
        title
      }
    }
  }
"""
user(id: ID!): User

"""
Paginated list of all users using cursor-based pagination.
Supports up to 100 users per request.

Arguments:
  first: Maximum number of users to return (default: 20, max: 100)
  after: Cursor from previous response for pagination

Example:
  query {
    users(first: 10, after: "cursor_xyz") {
      edges {
        node {
          id
          email
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
"""
users(first: Int, after: String): UserConnection

"""
Represents a system user with email authentication.

Fields:
  - id: Unique system identifier (immutable)
  - email: Contact email (unique across system)
  - posts: All posts authored by this user (reverse relation)
  - createdAt: Account creation timestamp (UTC)
"""
type User {
  id: ID!
  email: String!
  posts: [Post!]!
  createdAt: DateTime!
}

type Product {
  """
  [Copilot generates here]
  """
  id: ID!

  """
  [Copilot generates here]
  """
  name: String!
}

"""
Unique identifier for the product (UUID).
"""
id: ID!

"""
Human-readable product name. Must be unique within the catalog.
"""
name: String!

"""
Connection pattern for cursor-based pagination. Allows efficient
browsing of large datasets without loading all records.

Pagination logic:
  - first: Forward pagination (limit)
  - after: Forward pagination (cursor)
  - last: Backward pagination (limit)
  - before: Backward pagination (cursor)

Example:
  query {
    users(first: 20, after: "cursor_abc") {
      edges {
        node { id, name }
        cursor
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
"""
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

"""
Wraps a single user result in cursor pagination context.
The cursor value is opaque and should be treated as a string.
"""
type UserEdge {
  node: User!
  cursor: String!
}

"""
Pagination metadata. Use hasNextPage to determine if more results exist.
"""
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

"""
Filters for advanced product search. All filters are combined with AND logic.
Example: minPrice AND maxPrice AND category AND status
"""
input ProductFilter {
  """
  Price range (inclusive). Both must be positive integers.
  Example: minPrice: 1000, maxPrice: 50000 (prices in cents)
  """
  minPrice: Int
  maxPrice: Int

  """
  Filter by category slug. Case-insensitive exact match.
  Valid values: electronics, clothing, home, sports
  """
  category: String

  """
  Only return products with this status.
  Values: ACTIVE (default), ARCHIVED, DRAFT
  """
  status: ProductStatus = ACTIVE

  """
  Search across product name and description (fuzzy match).
  Minimum 3 characters. Performance: ~50ms for large catalogs.
  """
  query: String
}

type Query {
  """
  Search products with advanced filtering and sorting.

  Arguments:
    filter: Optional ProductFilter object
    sortBy: Sort by PRICE_ASC, PRICE_DESC, CREATED_AT_DESC (default)
    first: Max results (default: 20, max: 100)

  Performance: Indexed on category and status. Query time: <200ms typical.

  Errors:
    - INVALID_FILTER: malformed filter object
    - QUERY_TOO_SHORT: search query < 3 chars
    - RATE_LIMITED: exceeded 100 requests/minute

  Example:
    query {
      products(
        filter: { minPrice: 1000, category: "electronics" }
        sortBy: PRICE_ASC
        first: 20
      ) {
        edges { node { id, name, price } }
      }
    }
  """
  products(
    filter: ProductFilter
    sortBy: ProductSort = CREATED_AT_DESC
    first: Int = 20
  ): ProductConnection!
}

"""
Result of a user account creation attempt.
Check the success field to determine if account was created.
"""
type CreateUserPayload {
  """
  True if user account created successfully.
  False if validation errors occurred (see errors field).
  """
  success: Boolean!

  """
  The created user (null if success is false).
  """
  user: User

  """
  List of validation errors if creation failed.
  Example: [{ field: "email", message: "Already in use" }]
  """
  errors: [ValidationError!]!
}

type Mutation {
  """
  Create a new user account. Email must be unique.

  Arguments:
    email: Valid email address (will be normalized to lowercase)
    password: Minimum 8 characters, must include letter + number

  On success: Creates user, returns CreateUserPayload with success=true
  On failure: Returns validation errors, does NOT create user

  Errors:
    - EMAIL_EXISTS: Email already registered
    - INVALID_EMAIL: Email format invalid
    - WEAK_PASSWORD: Password doesn't meet security requirements
    - RATE_LIMITED: Max 5 signup attempts per IP per hour

  Example:
    mutation {
      createUser(
        email: "user@example.com"
        password: "SecurePass123"
      ) {
        success
        user { id, email }
        errors { field, message }
      }
    }
  """
  createUser(
    email: String!
    password: String!
  ): CreateUserPayload!
}

# Claude generates descriptions with proper formatting
# Paste back into schema.graphql