GO-4459: Update interfaces and comments

cmd/api/auth/service.go

@@ -27,8 +27,7 @@ func NewService(mw service.ClientCommandsServer) *AuthService {
 	return &AuthService{mw: mw}
 }
 
-// GenerateNewChallenge calls mw.AccountLocalLinkNewChallenge(...)
-// and returns the challenge ID, or an error if it fails.
+// GenerateNewChallenge calls AccountLocalLinkNewChallenge and returns the challenge ID, or an error if it fails.
 func (s *AuthService) GenerateNewChallenge(ctx context.Context, appName string) (string, error) {
 	resp := s.mw.AccountLocalLinkNewChallenge(ctx, &pb.RpcAccountLocalLinkNewChallengeRequest{AppName: "api-test"})
 
@@ -39,8 +38,7 @@ func (s *AuthService) GenerateNewChallenge(ctx context.Context, appName string)
 	return resp.ChallengeId, nil
 }
 
-// SolveChallengeForToken calls mw.AccountLocalLinkSolveChallenge(...)
-// and returns the session token + app key, or an error if it fails.
+// SolveChallengeForToken calls AccountLocalLinkSolveChallenge and returns the session token + app key, or an error if it fails.
 func (s *AuthService) SolveChallengeForToken(ctx context.Context, challengeID, code string) (sessionToken, appKey string, err error) {
 	if challengeID == "" || code == "" {
 		return "", "", ErrInvalidInput

cmd/api/object/service.go

@@ -47,12 +47,11 @@ type ObjectService struct {
 	AccountInfo *model.AccountInfo
 }
 
-// NewService creates a new object service
 func NewService(mw service.ClientCommandsServer) *ObjectService {
 	return &ObjectService{mw: mw}
 }
 
-// ListObjects retrieves a list of objects in a specific space
+// ListObjects retrieves a paginated list of objects in a specific space.
 func (s *ObjectService) ListObjects(ctx context.Context, spaceId string, offset int, limit int) (objects []Object, total int, hasMore bool, err error) {
 	resp := s.mw.ObjectSearch(ctx, &pb.RpcObjectSearchRequest{
 		SpaceId: spaceId,
@@ -112,7 +111,7 @@ func (s *ObjectService) ListObjects(ctx context.Context, spaceId string, offset
 	return objects, total, hasMore, nil
 }
 
-// GetObject retrieves a single object by its ID in a specific space
+// GetObject retrieves a single object by its ID in a specific space.
 func (s *ObjectService) GetObject(ctx context.Context, spaceId string, objectId string) (Object, error) {
 	resp := s.mw.ObjectShow(ctx, &pb.RpcObjectShowRequest{
 		SpaceId:  spaceId,
@@ -148,7 +147,7 @@ func (s *ObjectService) GetObject(ctx context.Context, spaceId string, objectId
 	return object, nil
 }
 
-// CreateObject creates a new object in a specific space
+// CreateObject creates a new object in a specific space.
 func (s *ObjectService) CreateObject(ctx context.Context, spaceId string, request CreateObjectRequest) (Object, error) {
 	resp := s.mw.ObjectCreate(ctx, &pb.RpcObjectCreateRequest{
 		Details: &types.Struct{
@@ -197,13 +196,13 @@ func (s *ObjectService) CreateObject(ctx context.Context, spaceId string, reques
 	return object, nil
 }
 
-// UpdateObject updates an existing object in a specific space
+// UpdateObject updates an existing object in a specific space.
 func (s *ObjectService) UpdateObject(ctx context.Context, spaceId string, objectId string, request UpdateObjectRequest) (Object, error) {
 	// TODO: Implement logic to update an existing object
 	return Object{}, ErrNotImplemented
 }
 
-// ListTypes returns the list of types in a specific space
+// ListTypes returns a paginated list of types in a specific space.
 func (s *ObjectService) ListTypes(ctx context.Context, spaceId string, offset int, limit int) (types []ObjectType, total int, hasMore bool, err error) {
 	resp := s.mw.ObjectSearch(ctx, &pb.RpcObjectSearchRequest{
 		SpaceId: spaceId,
@@ -252,7 +251,7 @@ func (s *ObjectService) ListTypes(ctx context.Context, spaceId string, offset in
 	return objectTypes, total, hasMore, nil
 }
 
-// ListTemplates returns the list of templates in a specific space
+// ListTemplates returns a paginated list of templates in a specific space.
 func (s *ObjectService) ListTemplates(ctx context.Context, spaceId string, typeId string, offset int, limit int) (templates []ObjectTemplate, total int, hasMore bool, err error) {
 	// First, determine the type ID of "ot-template" in the space
 	templateTypeIdResp := s.mw.ObjectSearch(ctx, &pb.RpcObjectSearchRequest{
@@ -330,7 +329,7 @@ func (s *ObjectService) ListTemplates(ctx context.Context, spaceId string, typeI
 	return templates, total, hasMore, nil
 }
 
-// GetDetails returns the list of details from the ObjectShowResponse
+// GetDetails returns the list of details from the ObjectShowResponse.
 func (s *ObjectService) GetDetails(resp *pb.RpcObjectShowResponse) []Detail {
 	return []Detail{
 		{
@@ -379,7 +378,7 @@ func (s *ObjectService) getTags(resp *pb.RpcObjectShowResponse) []Tag {
 	return tags
 }
 
-// GetBlocks returns the list of blocks from the ObjectShowResponse
+// GetBlocks returns the list of blocks from the ObjectShowResponse.
 func (s *ObjectService) GetBlocks(resp *pb.RpcObjectShowResponse) []Block {
 	blocks := []Block{}
 
@@ -425,7 +424,7 @@ func (s *ObjectService) GetBlocks(resp *pb.RpcObjectShowResponse) []Block {
 	return blocks
 }
 
-// mapAlign maps the protobuf BlockAlign to a string
+// mapAlign maps the protobuf BlockAlign to a string.
 func mapAlign(align model.BlockAlign) string {
 	switch align {
 	case model.Block_AlignLeft:
@@ -441,7 +440,7 @@ func mapAlign(align model.BlockAlign) string {
 	}
 }
 
-// mapVerticalAlign maps the protobuf BlockVerticalAlign to a string
+// mapVerticalAlign maps the protobuf BlockVerticalAlign to a string.
 func mapVerticalAlign(align model.BlockVerticalAlign) string {
 	switch align {
 	case model.Block_VerticalAlignTop:

cmd/api/search/service.go

@@ -22,7 +22,7 @@ var (
 )
 
 type Service interface {
-	Search(ctx context.Context) ([]object.Object, error)
+	Search(ctx context.Context, searchQuery string, objectType string, offset, limit int) (objects []object.Object, total int, hasMore bool, err error)
 }
 
 type SearchService struct {
@@ -36,6 +36,7 @@ func NewService(mw service.ClientCommandsServer, spaceService *space.SpaceServic
 	return &SearchService{mw: mw, spaceService: spaceService, objectService: objectService}
 }
 
+// Search retrieves a paginated list of objects from all spaces that match the search parameters.
 func (s *SearchService) Search(ctx context.Context, searchQuery string, objectType string, offset, limit int) (objects []object.Object, total int, hasMore bool, err error) {
 	spaces, _, _, err := s.spaceService.ListSpaces(ctx, 0, 100)
 	if err != nil {

cmd/api/server/middleware.go

@@ -10,13 +10,13 @@ import (
 	"github.com/anyproto/anytype-heart/core/anytype/account"
 )
 
-// // TODO: User represents an authenticated user with permissions
+// TODO: User represents an authenticated user with permissions
 type User struct {
 	ID          string
 	Permissions string // "read-only" or "read-write"
 }
 
-// initAccountInfo retrieves the account information from the account service
+// initAccountInfo retrieves the account information from the account service.
 func (s *Server) initAccountInfo() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		// TODO: consider not fetching account info on every request; currently used to avoid inconsistencies on logout/login
@@ -39,7 +39,7 @@ func (s *Server) initAccountInfo() gin.HandlerFunc {
 	}
 }
 
-// TODO: AuthMiddleware to ensure the user is authenticated
+// TODO: AuthMiddleware ensures the user is authenticated.
 func (s *Server) AuthMiddleware() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		token := c.GetHeader("Authorization")
@@ -60,7 +60,7 @@ func (s *Server) AuthMiddleware() gin.HandlerFunc {
 	}
 }
 
-// TODO: PermissionMiddleware to ensure the user has the required permissions
+// TODO: PermissionMiddleware ensures the user has the required permissions.
 func (s *Server) PermissionMiddleware(requiredPermission string) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		user, exists := c.Get("user")

cmd/api/server/server.go

@@ -21,7 +21,7 @@ const (
 	readHeaderTimeout = 5 * time.Second
 )
 
-// Server wraps the HTTP server logic.
+// Server wraps the HTTP server and service logic.
 type Server struct {
 	engine *gin.Engine
 	srv    *http.Server
@@ -33,8 +33,7 @@ type Server struct {
 	searchService *search.SearchService
 }
 
-// NewServer constructs a new Server with default config
-// and sets up routes via your router.go
+// NewServer constructs a new Server with default config and sets up the routes.
 func NewServer(mw service.ClientCommandsServer, mwInternal core.MiddlewareInternal) *Server {
 	s := &Server{
 		mwInternal:    mwInternal,
@@ -54,13 +53,13 @@ func NewServer(mw service.ClientCommandsServer, mwInternal core.MiddlewareIntern
 	return s
 }
 
-// ListenAndServe starts the HTTP server
+// ListenAndServe starts the HTTP server.
 func (s *Server) ListenAndServe() error {
 	fmt.Printf("Starting API server on %s\n", httpPort)
 	return s.srv.ListenAndServe()
 }
 
-// Shutdown gracefully stops the server
+// Shutdown gracefully stops the server.
 func (s *Server) Shutdown(ctx context.Context) error {
 	fmt.Println("Shutting down API server...")
 	return s.srv.Shutdown(ctx)

cmd/api/space/service.go

@@ -30,6 +30,7 @@ var (
 type Service interface {
 	ListSpaces(ctx context.Context, offset int, limit int) ([]Space, int, bool, error)
 	CreateSpace(ctx context.Context, name string) (Space, error)
+	ListMembers(ctx context.Context, spaceId string, offset int, limit int) ([]Member, int, bool, error)
 }
 
 type SpaceService struct {
@@ -41,6 +42,7 @@ func NewService(mw service.ClientCommandsServer) *SpaceService {
 	return &SpaceService{mw: mw}
 }
 
+// ListSpaces returns a paginated list of spaces for the account.
 func (s *SpaceService) ListSpaces(ctx context.Context, offset int, limit int) (spaces []Space, total int, hasMore bool, err error) {
 	resp := s.mw.ObjectSearch(ctx, &pb.RpcObjectSearchRequest{
 		SpaceId: s.AccountInfo.TechSpaceId,
@@ -100,6 +102,7 @@ func (s *SpaceService) ListSpaces(ctx context.Context, offset int, limit int) (s
 	return spaces, total, hasMore, nil
 }
 
+// CreateSpace creates a new space with the given name and returns the space info.
 func (s *SpaceService) CreateSpace(ctx context.Context, name string) (Space, error) {
 	iconOption, err := rand.Int(rand.Reader, big.NewInt(13))
 	if err != nil {
@@ -126,6 +129,7 @@ func (s *SpaceService) CreateSpace(ctx context.Context, name string) (Space, err
 	return s.getWorkspaceInfo(resp.SpaceId)
 }
 
+// ListMembers returns a paginated list of members in the space with the given ID.
 func (s *SpaceService) ListMembers(ctx context.Context, spaceId string, offset int, limit int) (members []Member, total int, hasMore bool, err error) {
 	resp := s.mw.ObjectSearch(ctx, &pb.RpcObjectSearchRequest{
 		SpaceId: spaceId,
@@ -181,7 +185,7 @@ func (s *SpaceService) ListMembers(ctx context.Context, spaceId string, offset i
 	return members, total, hasMore, nil
 }
 
-// getWorkspaceInfo returns the workspace info for the space with the given ID
+// getWorkspaceInfo returns the workspace info for the space with the given ID.
 func (s *SpaceService) getWorkspaceInfo(spaceId string) (space Space, err error) {
 	workspaceResponse := s.mw.WorkspaceOpen(context.Background(), &pb.RpcWorkspaceOpenRequest{
 		SpaceId:  spaceId,