// 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 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 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 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 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 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 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 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 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 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 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 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 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 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)

	// GetSpecifiedUserSourceLink GetUserSourceLinks retrieves the links between a user and a specific source in the OtterSpace graph.
	// It returns a map of source domains to user-source relationships, and an error if the operation fails.
	GetSpecifiedUserSourceLink(ctx context.Context, anthroveUserID models.AnthroveUserID, sourceDisplayName string) (map[string]models.AnthroveUserRelationship, error)

	// 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 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)

	// GetUserFavoritePostsWithPagination gets all user favorites with relation and sources for the given user
	GetUserFavoritePostsWithPagination(ctx context.Context, anthroveUserID models.AnthroveUserID, skip int, limit int) (*models.FavoriteList, error)

	// GetUserTagsTroughFavedPosts returns a list of Tags that the user hs favorites through a post
	GetUserTagsTroughFavedPosts(ctx context.Context, anthroveUserID models.AnthroveUserID) ([]models.TagsWithFrequency, error)

	// GetAllTags returns a list of Tags that the user hs favorites through a post
	GetAllTags(ctx context.Context) ([]models.TagsWithFrequency, error)

	// GetAllSources returns a list of Sources in the database
	GetAllSources(ctx context.Context) ([]models.AnthroveSource, error)

	// GetSourceByURL returns the Source Node based on the URL
	GetSourceByURL(ctx context.Context, sourceUrl string) (*models.AnthroveSource, error)
}