diff --git a/pkg/graph/graph.go b/pkg/graph/graph.go index f4be082..92d9bb2 100644 --- a/pkg/graph/graph.go +++ b/pkg/graph/graph.go @@ -1,54 +1,96 @@ +// Package graph provides a client for using the OtterSpace API. +// +// This package provides a client to interact with the OtterSpace API. It includes +// methods for all API endpoints, and convenience methods for common tasks. +// +// This is a simple usage example: +// +// package main +// +// import ( +// "context" +// "fmt" +// "git.dragse.it/anthrove/otter-space-sdk/pkg/models" +// "git.dragse.it/anthrove/otter-space-sdk/pkg/graph" +// ) +// +// func main() { +// client := graph.NewGraphConnection() +// err := client.Connect(context.Background(), "your-endpoint", "your-username", "your-password") +// if err != nil { +// fmt.Println(err) +// return +// } +// // further usage of the client... +// } package graph import ( "context" - "git.dragse.it/anthrove/otter-space-sdk/pkg/models" ) +// OtterSpace provides an interface for interacting with the OtterSpace API. +// It includes methods for connecting to the API, adding and linking users, posts, and sources, +// and retrieving information about users and posts. type OtterSpace interface { - // Connect sets up a connection to the endpoint using the provided username and password + // Connect sets up a connection to the OtterSpace API endpoint using the provided username and password. + // It returns an error if the connection cannot be established. Connect(ctx context.Context, endpoint string, username string, password string) error - // AddUserWithRelationToSource uploads an Anthrove user to the graph - AddUserWithRelationToSource(ctx context.Context, anthroveUserID models.AnthroveUserID, sourceDomain string, userID string, username string) (*models.AnthroveUser, error) + // AddUserWithRelationToSource adds a new user to the OtterSpace graph and associates them with a source. + // It returns the newly created user and an error if the operation fails. + AddUserWithRelationToSource(ctx context.Context, anthroveUserID models.AnthroveUserID, sourceDomain string, userID string, username string) error - // AddSource uploads an Anthrove source to the graph + // AddSource adds a new source to the OtterSpace graph. + // It returns an error if the operation fails. AddSource(ctx context.Context, anthroveSource *models.AnthroveSource) error - // AddPost uploads an Anthrove post to the graph + // AddPost adds a new post to the OtterSpace graph. + // It returns an error if the operation fails. AddPost(ctx context.Context, anthrovePost *models.AnthrovePost) error - // AddTagWithRelationToPost uploads a tag associated with an Anthrove post to the graph + // AddTagWithRelationToPost adds a new tag to the OtterSpace graph and associates it with a post. + // It returns an error if the operation fails. AddTagWithRelationToPost(ctx context.Context, anthrovePostID models.AnthrovePostID, anthroveTag *models.AnthroveTag) error - // LinkPostWithSource establishes a link between a post and a source in the graph + // LinkPostWithSource establishes a link between a post and a source in the OtterSpace graph. + // It returns an error if the operation fails. LinkPostWithSource(ctx context.Context, anthrovePostID models.AnthrovePostID, anthroveSourceDomain string, anthrovePostRelationship *models.AnthrovePostRelationship) error - // LinkUserWithPost establishes a link between a user and a post in the graph + // LinkUserWithPost establishes a link between a user and a post in the OtterSpace graph. + // It returns an error if the operation fails. LinkUserWithPost(ctx context.Context, anthroveUser *models.AnthroveUser, anthrovePost *models.AnthrovePost) error - // CheckUserPostLink checks if a link between a user and a post exists in the graph + // CheckUserPostLink checks if a link between a user and a post exists in the OtterSpace graph. + // It returns true if the link exists, false otherwise, and an error if the operation fails. CheckUserPostLink(ctx context.Context, anthroveUserID models.AnthroveUserID, sourcePostID string, sourceUrl string) (bool, error) - // CheckPostNodeExistsByAnthroveID checks if an Anthrove post node exists in the graph by its Anthrove ID + // CheckPostNodeExistsByAnthroveID checks if a post node exists in the OtterSpace graph by its Anthrove ID. + // It returns the post if it exists, a boolean indicating whether the post was found, and an error if the operation fails. CheckPostNodeExistsByAnthroveID(ctx context.Context, anthrovePost *models.AnthrovePost) (*models.AnthrovePost, bool, error) - // CheckPostNodeExistsBySourceURL checks if an Anthrove post node exists in the graph by its source URL + // CheckPostNodeExistsBySourceURL checks if a post node exists in the OtterSpace graph by its source URL. + // It returns the post if it exists, a boolean indicating whether the post was found, and an error if the operation fails. CheckPostNodeExistsBySourceURL(ctx context.Context, sourceUrl string) (*models.AnthrovePost, bool, error) - // CheckPostNodeExistsBySourceID checks if an Anthrove post node exists in the graph by its source ID + // CheckPostNodeExistsBySourceID checks if a post node exists in the OtterSpace graph by its source ID. + // It returns the post if it exists, a boolean indicating whether the post was found, and an error if the operation fails. CheckPostNodeExistsBySourceID(ctx context.Context, sourcePostID string) (*models.AnthrovePost, bool, error) - // GetUserFavoriteCount retrieves the count of user's favorite posts + // GetUserFavoriteCount retrieves the count of a user's favorite posts from the OtterSpace graph. + // It returns the count and an error if the operation fails. GetUserFavoriteCount(ctx context.Context, anthroveUserID models.AnthroveUserID) (int64, error) - // GetUserSourceLinks retrieves the links between a user and sources in the graph + // GetUserSourceLinks retrieves the links between a user and sources in the OtterSpace graph. + // It returns a map of source domains to user-source relationships, and an error if the operation fails. GetUserSourceLinks(ctx context.Context, anthroveUserID models.AnthroveUserID) (map[string]models.AnthroveUserRelationship, error) - // GetAnthroveUser retrieves an Anthrove user from the graph by their ID + // GetAnthroveUser retrieves a user from the OtterSpace graph by their ID. + // It returns the user and an error if the operation fails. GetAnthroveUser(ctx context.Context, anthroveUserID models.AnthroveUserID) (*models.AnthroveUser, error) - // GetAllAnthroveUserIDs retrieves all Anthrove user IDs from the graph + // GetAllAnthroveUserIDs retrieves all user IDs from the OtterSpace graph. + // It returns a slice of user IDs and an error if the operation fails. GetAllAnthroveUserIDs(ctx context.Context) ([]models.AnthroveUserID, error) }