Parsee/src/include/AS.h

#ifndef PARSEE_AS_H
#define PARSEE_AS_H
/*-* 
 * Functions used to communicate with a Matrix server and execute actions 
 * over HTTP(S)+JSON. This effectively serves as Parsee's Matrix SDK.
 * TODO: Write my own RumiaSDK for the KappaChat project(not the client 
 * itself).
 * --------
 * Writren-By: LDA */

#include <Cytoplasm/HttpClient.h>
#include <Cytoplasm/Json.h>

#include <Parsee.h>
#include <Routes.h>

/** Verifies a request from the homeserver to match the {hs_token}.
 * ----------------
 * Returns: A JSON error message[HEAP] | NULL on success 
 * Thrasher: JsonFree */
extern HashMap * ASVerifyRequest(ParseeHttpArg *arg);

/* Authenticates a request with the correct as_token.
 * It does not send the request, however. */
extern void ASAuthenticateRequest(const ParseeConfig *, HttpClientContext *);

/* Registers an user through the Application Service API. Returns 
 * true if the user was created. */
extern bool ASRegisterUser(const ParseeConfig *, char *);

/* Pings the homeserver to get attention. */
extern void ASPing(const ParseeConfig *);

/** Joins a room from an {id} and a given {user} we want to masquerade 
 * as. 
 * --------------
 * Returns: the decoded room ID that was joined[HEAP] | NULL 
 * Modifies: the rooms/{user}s inner state */
extern char * ASJoin(const ParseeConfig *config, char *id, char *user);

/** Bans from a room a specific user
 * ---------------------
 * Returns: NOTHING
 * Modifies: the rooms state 
 * See-Also: ASJoin, ASKick, ASLeave */
extern void ASBan(const ParseeConfig *config, char *room, char *user);

/** Kicks from a room a specific user
 * ---------------------
 * Returns: NOTHING
 * Modifies: the rooms state 
 * See-Also: ASJoin, ASBan, ASLeave */
extern void ASKick(const ParseeConfig *, char *room, char *user);

/** Makes a specific user leave the room
 * ---------------------
 * Returns: NOTHING
 * Modifies: the rooms state 
 * See-Also: ASJoin, ASKick, ASBan */
extern void ASLeave(const ParseeConfig *config, char *room, char *user);

/* Invites from a room a specific user */
extern void ASInvite(const ParseeConfig *, char *, char *);

/* Finds an event from a room ID and event ID */
extern HashMap * ASFind(const ParseeConfig *, char *, char *);

/* Sends a message event with a specific type and body.
 * Said body is freed during the function's execution. */
extern char * ASSend(const ParseeConfig *, char *, char *, char *, HashMap *);
extern void ASType(const ParseeConfig *, char *, char *, bool);
extern void ASPresence(const ParseeConfig *, char *, char *, char *);

/* Redacts an event from a room with a specific user */
extern void ASRedact(const ParseeConfig *, char *room, char *user, char *e_id);

/* Sets a state event with a specific type and body */
extern void ASSetState(const ParseeConfig *conf, char *id, char *type, char *key, char *mask, HashMap *event);

/** Gets the content for a PL event in the room pointed by {id}
 * ------------------------
 * Returns: A valid JSON object[HEAP] | NULL 
 * Thrasher: JsonFree 
 * See-Also: ASSetPL */
extern HashMap *ASGetPL(const ParseeConfig *conf, char *id);

/** Sets the content for a PL event in the room pointed by {id} if 
 * possible.
 * ------------------------
 * Returns: NOTHING
 * Modifies: the room pointed by {id}
 * See-Also: ASGetPL */
extern void ASSetPL(const ParseeConfig *conf, char *id, HashMap *m);

/** Creates a room, with a masquerade user ({by}) as its creator and an 
 * optional {alias}.
 * --------
 * Returns: a valid room ID[HEAP] | NULL
 * Modifies: NOTHING
 * See-Also: ASCreateDM */
extern char * ASCreateRoom(const ParseeConfig *c, char *by, char *alias);

/** Creates a new DM {with} a Matrix user, from a puppet {by}
 * --------
 * Returns: a valid room ID[HEAP] | NULL
 * Modifies: NOTHING
 * See-Also: ASCreateRoom */
extern char * ASCreateDM(const ParseeConfig *c, char *by, char *with);

/** Sets the user's global display{name}
 * --------
 * Returns: NOTHING
 * Modifies: the users' status in Matrix
 * See-Also: ASGetName, ASSetStatus, ASSetAvatar */
extern void ASSetName(const ParseeConfig *c, char *user, char *name);

/** Sets the {user}'s global avatar, as an {mxc} URI
 * --------
 * Returns: NOTHING
 * Modifies: the users' status in Matrix
 * See-Also: ASGetName, ASSetStatus */
extern void ASSetAvatar(const ParseeConfig *c, char *user, char *mxc);

typedef enum UserStatus {
    USER_STATUS_ONLINE,
    USER_STATUS_OFFLINE,
    USER_STATUS_UNAVAILABLE
} UserStatus;
/** Sets the user's status and message, to be seen by other clients.
 * --------
 * Returns: NOTHING
 * Modifies: the users' status in Matrix
 * See-Also: https://spec.matrix.org/v1.11/client-server-api/#put_matrixclientv3presenceuseridstatus, ASSetName, ASSetAvatar */
extern void ASSetStatus(const ParseeConfig *c, char *user, UserStatus status, char *msg);

/** Returns the user's name in a room, or a copy of the MXID itself, to be 
 * Free'd
 * ------------- 
 * Returns: The user's name in the room[HEAP] | A copy of {user}[HEAP]
 * Thrasher: Free
 * Modifies: NOTHING */
extern char * ASGetName(const ParseeConfig *c, char *room, char *user);

/** Uploads data to Matrix to be used later
 * ----------------
 * Returns: A valid MXC URI[HEAP] | NULL
 * Thrasher: Free 
 * Modifies: the internal Matrix homeserver's media repository
 * See-Also: ASReupload */
extern char * ASUpload(const ParseeConfig *c, Stream *from, unsigned int size, char *mime);

/** Reuploads a HTTP URL to Matrix, with an optional MIME type returned.
 * ----------------
 * Returns: A valid MXC URI[HEAP] | NULL
 * Thrasher: Free 
 * Modifies: the internal Matrix homeserver's media repository, {from}s server
 * See-Also: ASUpload */
extern char * ASReupload(const ParseeConfig *c, char *from, char **mime);

/** Gets up to {n} relations to an event(with a specific type, optionally).
 * ----------
 * Returns: A list of JSON objects[HEAP]
 * Thrasher: ASFreeRelations
 * See-Also: https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv1roomsroomidrelationseventid */
extern Array * ASGetRelations(const ParseeConfig *c, size_t n, char *room, char *event, char *type);

/** Destroys a relation list created by {ASGetRelations}
 * ------------
 * Returns: NOTHING
 * Thrashes: {relations}
 * See-Also: ASGetRelations */
extern void ASFreeRelations(Array *relations);
#endif