root/feedmelinks/aim/bot/TODO.txt

/*[introduces the notion of polite software and the perlish $_ / dwim notion of the last linked thing becing the default

Getting started
========= ========= ========= =========

1. you click the AIM link on the FML portal or your links page (/img/AIM-icon.png)

        2. THE BOT looks up your buddy name in the FML database to see if your AIM is already linked to a (your) Feed Me Links account, via a REST call.
                TODO: that url is: http://feedmelinks.com/api/backroom/is_im_account_known&user=some_im_name
                The database will repond in 1 of 4 ways:
                        2.0:  FML has never seen this AIM name
                                        If the AIM account is *NOT* found to be associated with any FML account,
                                        then the bot responds with SOME HELPFUL OPTIONS ("recent", "signup", and "activate" [for existing users] - a user-friendly link that associates the AIM account w/an FML account
                                        TODO: http://feedmelinks.com/set-up/IM (which combines /account + /validate/IM) need url to add an IM address (if one exists, should flag) and show validation phrase on success
                                        (this is a nice case because it's the default, and it combines two steps into one for the user)

                        2.1:  The AIM name is associated with a single account foo" BUT has NOT YET been used with FML
                                        If the AIM account *is* found by ONE user, but has not yet been used w/FML before (say, because you just recently signed up for AIM (or FML), 
                                        or you recently changed your AIM Account), then the bot will THANK YOU FOR USING IT and 
                                        send you helpful information plus the user-friendly VALIDATION LINK [1] so that you can validate your account and start playing with the bot.
                                        TODO: that URL is: http://feedmelinks.com/validate/IM

                                        (the bot then waits.)

                                        if you don't get distracted and go away, then,
                                        2.1.0: you click the link, 
                                        2.1.1: copy your validation phrase, and paste it into the IM window, and send
                                        
                                        (the bot wakes up again!)

                                        the bot accepts your phrase, and compares it to the server's notion of what your validation phrase should be via a REST call.
                                        TODO: that URL is: http://www.feedmelinks.com/api/backroom/get_im_validation_phrase_for_user&user=jm3

                                        If the bot finds that the phrases match, the bot will call a restricted (authenticated) REST API function to validate (link) the user's AIM and FML accounts
                                        validating will also RUDE-SOLO out the AIM account from anyone else's account, and should send an email to those FML account holders.
                                        TODO: that url is: http://www.feedmelinks.com/api/backroom/validate_users_im_name&user=klaus_kinski

                        2.1V: The AIM name is associated with a single account, owned by user "foo", who has already validated his account
                                        In this case, you are automatically authorized to start linking via the bot, EVEN IF YOU ARE NOT CURRENTLY LOGGED IN VIA FML -- WAY COOL. 

                        2.N:  The AIM name is associated with N different accounts
                                        In this case previous validation DOESN'T MATTER -- you MUST validate the account, which will rude-solo DELETE the aim from any other associate FML accounts
                                        TODO: that url is: http://www.feedmelinks.com/api/backroom/validate_users_im_name&user=klaus_kinski
        
                        (the bot now knows who you are on FML and which IM account you are communicating through (they don't need to be similar/same, in other words))

The bot now requests credentials on behalf of the user to act as an authenticated proxy for the user, effectively BECOMING that FML user for purposes of linking, etc

(the credentials are not stored but generated on the fly via REST)
TODO: that url is: http://www.feedmelinks.com/api/backroom/get_sock_puppet&user=jm3

the bot can then link as the user
TODO: that url is: http://feedmelinks.com/api/add?url=http://jm3.net&name=jm3+baba333+in+this%20house!&tags=movies,+foo,+bar,baz&comment=i+love+this+game+so+much. 

linking works as follows: TODO: http://feedmelinks.com/aim/help

FIXME: can the bot say hello when you open the window automatically?