syntax = "v1"
info (
 title: "User service reference"
 version: "1.0.0"
)
// Stable public errors are shared by Go code and the API document.
error (
 Unauthenticated 401 "UNAUTHENTICATED" "authentication required"
 Forbidden 403 "FORBIDDEN" "permission denied"
 UserNotFound 404 "USER_NOT_FOUND" "user not found"
 EmailTaken 409 "EMAIL_TAKEN" "email already in use"
 InvalidUser 400 "INVALID_USER" "invalid user"
 InvalidPage 400 "INVALID_PAGE" "invalid pagination"
)
auth AdminAuth (
 type: bearer
 middleware: Auth
 description: "Use an administrator token for writes, or a read-only token for GET requests"
)
type (
 UserResp {
  ID int64 `json:"id"`
  Name string `json:"name"`
  Email string `json:"email"`
  CreatedAt string `json:"createdAt"`
  UpdatedAt string `json:"updatedAt"`
 }
 CreateUserReq {
  Name string `json:"name" binding:"required,max=100"`
  Email string `json:"email" binding:"required,email,max=254"`
 }
 UserIDReq {
  ID int64 `path:"id,range=[1:9007199254740991]"`
 }
 UpdateUserReq {
  ID int64 `path:"id,range=[1:9007199254740991]"`
  Name string `json:"name" binding:"required,max=100"`
  Email string `json:"email" binding:"required,email,max=254"`
 }
 ListUsersReq {
  Page int `form:"page,default=1,range=[1:1000000]"`
  PageSize int `form:"pageSize,default=20,range=[1:100]"`
 }
 UserPageResp {
  Items []UserResp `json:"items"`
  Total int `json:"total"`
  Page int `json:"page"`
  PageSize int `json:"pageSize"`
 }
 ExportResp {
  DownloadURL string `json:"downloadUrl"`
 }
)
@server (
 group: user
 prefix: /api/v1
 auth: AdminAuth
 errors: Unauthenticated
)
service user-api {
 @doc (
  summary: "Create a user"
  description: "Normalizes the email, then commits user data and audit in one transaction"
  tags: users
 )
 @errors Forbidden, InvalidUser, EmailTaken
 @handler createUser
 @status 201
 post /users (CreateUserReq) returns (UserResp)
 @errors UserNotFound
 @handler getUser
 get /users/:id (UserIDReq) returns (UserResp)
 @errors InvalidPage
 @handler listUsers
 get /users (ListUsersReq) returns (UserPageResp)
 @errors Forbidden, InvalidUser, UserNotFound, EmailTaken
 @handler updateUser
 put /users/:id (UpdateUserReq) returns (UserResp)
 @errors Forbidden, UserNotFound
 @handler deleteUser
 delete /users/:id (UserIDReq)
 @doc "Export one user as a private text object with a short-lived download link"
 @errors Forbidden, UserNotFound
 @handler exportUser
 post /users/:id/export (UserIDReq) returns (ExportResp)
}