//
//  MGTwitterEngine.h
//  MGTwitterEngine
//
//  Created by Matt Gemmell on 10/02/2008.
//  Copyright 2008 Magic Aubergine.
//

#import <Cocoa/Cocoa.h>
#import <MGTwitterEngineDelegate.h>
#import <MGTwitterParserDelegate.h>

@interface MGTwitterEngine : NSObject <MGTwitterParserDelegate> {
    __weak NSObject <MGTwitterEngineDelegate> *_delegate;
    NSString *_username;
    NSString *_password;
    NSMutableArray *_connections;   // MGTwitterHTTPURLConnection objects
    NSString *_clientName;
    NSString *_clientVersion;
    NSString *_clientURL;
    NSString *_clientSourceToken;
    BOOL _secureConnection;
}

// Constructors
+ (MGTwitterEngine *)twitterEngineWithDelegate:(NSObject *)delegate;
- (MGTwitterEngine *)initWithDelegate:(NSObject *)delegate;

// Configuration and Accessors
+ (NSString *)version; // returns the version of MGTwitterEngine
- (NSString *)username;
- (NSString *)password;
- (void)setUsername:(NSString *)username password:(NSString *)password;
- (NSString *)clientName;
- (NSString *)clientVersion;
- (NSString *)clientURL;
- (NSString *)clientSourceToken;
- (void)setClientName:(NSString *)name version:(NSString *)version URL:(NSString *)url token:(NSString *)token;
- (BOOL)usesSecureConnection;
- (void)setUsesSecureConnection:(BOOL)flag;

// Connection methods
- (void)closeAllConnections;

// ======================================================================================================
// Twitter API methods
// See Twitter API docs at: http://groups.google.com/group/twitter-development-talk/web/api-documentation
// All methods below return a unique connection identifier.
// ======================================================================================================

// Account methods
- (NSString *)checkUserCredentials;
- (NSString *)endUserSession;
- (NSString *)enableUpdatesFor:(NSString *)username;          // i.e. follow
- (NSString *)disableUpdatesFor:(NSString *)username;         // i.e. no longer follow
- (NSString *)enableNotificationsFor:(NSString *)username;
- (NSString *)disableNotificationsFor:(NSString *)username;

// Retrieving updates
- (NSString *)getFollowedTimelineFor:(NSString *)username since:(NSDate *)date startingAtPage:(int)pageNum;
- (NSString *)getUserTimelineFor:(NSString *)username since:(NSDate *)date count:(int)numUpdates;     // max 20
- (NSString *)getUserUpdatesArchiveStartingAtPage:(int)pageNum;                                       // 80 per page
- (NSString *)getPublicTimelineSinceID:(int)updateID;
- (NSString *)getRepliesStartingAtPage:(int)pageNum;                                          // sent TO this user
- (NSString *)getFavoriteUpdatesFor:(NSString *)username startingAtPage:(int)pageNum;
- (NSString *)getUpdate:(int)updateID;

// Retrieving direct messages
- (NSString *)getDirectMessagesSince:(NSDate *)date startingAtPage:(int)pageNum;              // sent TO this user
- (NSString *)getDirectMessagesSinceID:(int)updateID startingAtPage:(int)pageNum;             // sent TO this user
- (NSString *)getSentDirectMessagesSince:(NSDate *)date startingAtPage:(int)pageNum;          // sent BY this user
- (NSString *)getSentDirectMessagesSinceID:(int)updateID startingAtPage:(int)pageNum;         // sent BY this user

// Retrieving user information
- (NSString *)getUserInformationFor:(NSString *)username;
- (NSString *)getUserInformationForEmail:(NSString *)email;
- (NSString *)getRecentlyUpdatedFollowersFor:(NSString *)username startingAtPage:(int)pageNum;
- (NSString *)getFollowersIncludingCurrentStatus:(BOOL)flag;
- (NSString *)getFeaturedUsers;

// Sending and editing updates
- (NSString *)sendUpdate:(NSString *)status;
- (NSString *)deleteUpdate:(int)updateID;                 // this user must be the AUTHOR
- (NSString *)markUpdate:(int)updateID asFavorite:(BOOL)flag;

// Sending and editing direct messages
- (NSString *)sendDirectMessage:(NSString *)message to:(NSString *)username;
- (NSString *)deleteDirectMessage:(int)updateID;          // this user must be the RECIPIENT

@end