endpoint

type CustomEndpoint[PP, QP, HP, CP, Req, Resp any] struct {
	Name               string
	Method             HTTPMethod
	Path               string
	Description        string
	RequestDescription string
	PathParams         PP
	QueryParams        QP
	HeaderParams       HP
	CookieParams       CP
	RequestBody        Req
	Responses          []Response[Resp]
	RequestKind        TSKind
	ResponseKind       TSKind
	HandlerFunc        gin.HandlerFunc
}

type Endpoint[PP, QP, HP, CP, Req, Resp any] struct {
	Name               string
	Method             HTTPMethod
	Path               string
	Description        string
	RequestDescription string
	PathParams         PP
	QueryParams        QP
	HeaderParams       HP
	CookieParams       CP
	RequestBody        Req
	Responses          []Response[Resp]
	HandlerFunc        func(pathParams PP, queryParams QP, headerParams HP, cookieParams CP, requestBody Req, ctx *gin.Context) (Response[Resp], error)
}

type EndpointLike interface {
	EndpointMeta() EndpointMeta
	GinHandler() gin.HandlerFunc
}

type EndpointMeta struct {
	Name               string
	Method             HTTPMethod
	Path               string
	Description        string
	RequestDescription string
	PathParamsType     reflect.Type
	QueryParamsType    reflect.Type
	HeaderParamsType   reflect.Type
	CookieParamsType   reflect.Type
	RequestBodyType    reflect.Type
	Responses          []ResponseMeta
}

type EndpointTSHints struct {
	RequestKind  TSKind
	ResponseKind TSKind
}

type EndpointTSHintsProvider interface {
	EndpointTSHints() EndpointTSHints
}

type FormData struct{}

type HTTPMethod string

type NoBody struct{}

type NoMessage struct{}

type NoParams struct{}

type RawBytes []byte

type Response[T any] struct {
	StatusCode  int    `json:"statusCode"`
	Body        T      `json:"body,omitempty"`
	Description string `json:"description,omitempty"`
}

type ResponseMeta struct {
	StatusCode  int
	BodyType    reflect.Type
	Description string
}

type ServerAPI struct {
	// BasePath is the URL prefix used for generated TS clients.
	// BasePath 用于生成 TS 客户端时的 URL 前缀。
	BasePath string

	// GroupPath is the router-group path used when registering handlers in gin.
	// GroupPath 是在 gin 中注册路由时使用的分组路径。
	GroupPath string

	// Endpoints contains all HTTP endpoints under this API group.
	// Endpoints 包含该 API 分组下的全部 HTTP 端点。
	Endpoints []EndpointLike
}

type StreamResponse struct{}

type TSInt64Mode string

type TSKind string

type UnifiedTSExportOptions struct {
	ServerTSPath    string
	WebSocketTSPath string
	SchemaTSPath    string
}

type WebSocketAPI struct {
	// BasePath is the URL prefix used for generated TS websocket clients.
	// BasePath 用于生成 TS websocket 客户端时的 URL 前缀。
	BasePath string

	// GroupPath is the router-group path used when registering websocket handlers in gin.
	// GroupPath 是在 gin 中注册 websocket 路由时使用的分组路径。
	GroupPath string

	// Endpoints contains all websocket endpoints under this API group.
	// Endpoints 包含该 API 分组下的全部 websocket 端点。
	Endpoints []WebSocketEndpointLike

	// DefaultClientMessageType is the default envelope type for endpoint.ClientMessageType.
	// DefaultClientMessageType 作为 endpoint.ClientMessageType 的默认封装类型。
	DefaultClientMessageType reflect.Type

	// DefaultServerMessageType is the default envelope type for endpoint.ServerMessageType.
	// DefaultServerMessageType 作为 endpoint.ServerMessageType 的默认封装类型。
	DefaultServerMessageType reflect.Type
}

type WebSocketContext struct {
	ID      string
	Conn    *websocket.Conn
	Request *http.Request
	// contains filtered or unexported fields
}

type WebSocketEndpoint struct {
	Name         string
	Path         string
	Description  string
	MessageTypes []string

	// Message types for TS generation. If ClientMessageType is nil, defaults to WebSocketMessage.
	// 用于 TS 生成的消息类型；若 ClientMessageType 为空则默认 WebSocketMessage。
	ClientMessageType  reflect.Type
	ServerMessageType  reflect.Type
	ClientPayloadTypes map[string]reflect.Type
	ServerPayloadTypes map[string]reflect.Type

	// Optional upgrader configuration. If zero-value, a default upgrader is used.
	// Upgrader 可选配置；若为空则使用默认 Upgrader。
	Upgrader websocket.Upgrader

	// Optional hooks.
	// 可选回调。
	OnConnect    func(ctx *WebSocketContext) error
	HandlerFunc  func(message any, ctx *WebSocketContext) (any, error)
	OnDisconnect func(ctx *WebSocketContext, err error)

	// Optional typed handlers based on message type.
	// When MessageHandlers is set, HandlerFunc is ignored.
	// 可选按消息类型分发的处理器；若设置则忽略 HandlerFunc。
	MessageHandlers   map[string]func(payload json.RawMessage, ctx *WebSocketContext) (any, error)
	MessageTypeGetter func(message any) (msgType string, payload json.RawMessage, err error)

	PingPeriod time.Duration
	PongWait   time.Duration
	ReadLimit  int64
	// contains filtered or unexported fields
}

type WebSocketEndpointLike interface {
	WebSocketMeta() WebSocketEndpointMeta
	GinHandler() gin.HandlerFunc
	SetFullPath(path string)
}

type WebSocketEndpointMeta struct {
	Name               string
	Path               string
	Description        string
	ClientMessageType  reflect.Type
	ServerMessageType  reflect.Type
	MessageTypes       []string
	ClientPayloadTypes map[string]reflect.Type
	ServerPayloadTypes map[string]reflect.Type
}

type WebSocketMessage struct {
	Type    string          `json:"type"`
	Payload json.RawMessage `json:"payload"`
}