1"""
2An ISO 8601-encoded datetime string.
3"""
4scalar DateTime
5
6"""
7A unique identifier.
8"""
9scalar JSON
10
11
12"""
13Directive to enforce role-based access control on fields and types.
14"""
15directive @auth(requires: Role = USER) on OBJECT | FIELD_DEFINITION
16
17"""
18Available roles for authorization.
19"""
20enum Role {
21  """Full system access"""
22  ADMIN
23  """Standard user access"""
24  USER
25  """Read-only access"""
26  GUEST
27}
28
29
30"""
31Information about pagination in a connection.
32"""
33type PageInfo {
34  """Whether there are more items after this page."""
35  hasNextPage: Boolean!
36  """Whether there are more items before this page."""
37  hasPreviousPage: Boolean!
38  """Cursor pointing to the first item in the page."""
39  startCursor: String
40  """Cursor pointing to the last item in the page."""
41  endCursor: String
42}
43
44"""
45Standard error payload for mutations.
46"""
47type UserError {
48  """Human-readable error message."""
49  message: String!
50  """Which input field caused the error, if applicable."""
51  field: [String!]
52}
53
54"""
55The primary User entity.
56"""
57type User {
58  """Unique identifier for the User."""
59  id: ID!
60  """Full name of the User."""
61  name: String!
62  """Email address of the User.""" @auth(requires: ADMIN)
63  """Role assigned to the User."""
64  role: UserRole!
65  """When the User was created."""
66  createdAt: DateTime!
67  """When the User was last updated."""
68  updatedAt: DateTime!
69}
70
71"""
72Role options for User.
73"""
74enum UserRole {
75  ADMIN
76  USER
77  VIEWER
78}
79
80"""
81A connection to a list of users.
82"""
83type UserConnection {
84  """List of edges containing user nodes."""
85  edges: [UserEdge!]!
86  """Pagination information."""
87  pageInfo: PageInfo!
88  """Total number of users matching the query."""
89  totalCount: Int!
90}
91
92"""
93An edge in a User connection.
94"""
95type UserEdge {
96  """The cursor for this edge."""
97  cursor: String!
98  """The User node."""
99  node: User
100}
101
102type Query {
103  """
104  Fetch a single User by ID.
105  """
106  user(id: ID!): User @auth(requires: USER)
107
108  """
109  Fetch a paginated list of users using cursor-based pagination.
110  """
111  users(
112    """Number of items to return."""
113    first: Int
114    """Cursor to start after."""
115    after: String
116    """Number of items from the end."""
117    last: Int
118    """Cursor to end before."""
119    before: String
120    """Filter by role."""
121    role: UserRole
122    """Search by name or email."""
123    search: String
124  ): UserConnection! @auth(requires: USER)
125}
126
127input CreateUserInput {
128  """Full name of the User."""
129  name: String!
130  """Email address of the User."""
131  email: String!
132  """Role to assign (defaults to USER)."""
133  role: UserRole
134}
135
136input UpdateUserInput {
137  """Updated name."""
138  name: String
139  """Updated email."""
140  email: String
141  """Updated role."""
142  role: UserRole
143}
144
145"""
146Payload returned by user mutations.
147"""
148type UserPayload {
149  """The affected User, or null if the operation failed."""
150  user: User
151  """Any validation or business logic errors."""
152  userErrors: [UserError!]!
153}
154
155type Mutation {
156  """
157  Create a new User.
158  """
159  userCreate(input: CreateUserInput!): UserPayload! @auth(requires: ADMIN)
160  
161  """
162  Update an existing User.
163  """
164  userUpdate(id: ID!, input: UpdateUserInput!): UserPayload! @auth(requires: USER)
165  
166  """
167  Delete a User.
168  """
169  userDelete(id: ID!): UserPayload! @auth(requires: ADMIN)
170}