README.rdoc in meal_ticket-0.0.0 vs README.rdoc in meal_ticket-0.1.0

@@ -1,7 +1,124 @@
-= meal_ticket
+MealTicket simplifies the process of authenticating with 3rd-party APIs by eliminating the stuff that's the same for everyone,
+letting you focus solely on the parts of authentication that matter to you.
 
-Description goes here.
+== Overview
+
+1. You pick a service you want to authenticate against
+1. You decide what permissions you need
+1. You redirect your user to something like facebook_auth_url(root_url, "user_photos,publish_stream")
+1. MealTicket handles the gruesome details of the various psuedo-OAuth schemes
+1. MealTicket redirects the user back to a url of your choice along with their access token
+
+== Currently Supported Services
+
+* facebook
+* flickr
+
+== Getting Started
+
+1. Require the gem. In your gemfile:
+
+    gem 'meal_ticket'
+
+1. Install the gem. In your console:
+
+    bundle install (or maybe 'sudo bundle install')
+
+1. Install MealTicket as middleware to handle cross-domain communication. In Rails, you'd add something like this to your application.rb:
+
+     module YourAppName
+       class Application < Rails::Application
+         config.middleware.use "MealTicket"
+
+1. Make meal_ticket URLs available to your views. In Rails, you'd add something like this to your application_helper.rb:
+
+    require 'meal_ticket'
+
+    module ApplicationHelper
+      include MealTicketRoutes
+    end
+
+1. Optionally, make meal_ticket URLs available to your controllers. In Rails, you'd add something like this to your application_controller.rb:
+
+    require 'meal_ticket'
+    
+    class ApplicationController < ActionController::Base
+      include MealTicketRoutes
+    end
+
+Now that you've finished installing MealTicket, look below for further instructions on how to connect with individual services.
+
+= Service-Specific Instructions
+
+For each service you want to integrate with, find it here and follow the steps to get your API keys.
+
+In general, you'll need to do a couple things for each service:
+
+1. Go to their site, get your API keys, and make global constants for them.
+1. Create a callback method to receive the user's access token. Make sure you also map a route for this method.
+
+== Facebook
+
+1. Log in to Facebook.
+1. Go to https://www.facebook.com/developers/apps.php and click the "Set Up New App" button.
+1. Fill out the forms to create a new app.
+1. Once you land on the "Edit" page, click the "Web Site" tab on the left.
+1. In the "Site Url" field, type the address of your site. For development, use something like +localhost:3000+. You may want
+   to set up a separate app for production.
+
+Create global constants that look something like this:
+
+  FACEBOOK_APP_ID = "158079864105359" # facebook calls this "App ID"
+  FACEBOOK_SECRET = "98882d6d6cf0d7b69a5de5cc43abc10" # facebook calls this "App Secret"
+  FACEBOOK_CALLBACK = "path/to/my/facebook/callback"  # whatever URL you've created to grab the user data and do something useful
+
+Now, redirect users to facebook_auth_url, passing the permissions you want to ask for. Like so:
+
+  # For a full list of permissions, see https://developers.facebook.com/docs/authentication/permissions/
+  redirect_to facebook_auth_url("user_photos,publish_stream")
+
+
+After they authenticate, they'll be redirected to your +FACEBOOK_CALLBACK+ URL with query string params like:
+
+  ?facebook[token]=q2jf89ojq.j32f|FQf9j23la&facebook[expires]=4829
+   - or, more legibly: -
+  {:facebook => {:token => "q2jf89ojq.j32f|FQf9j23la", :expires => "4829"}}
+
+
+Notes:
+
+* Your facebook "API key" is never actually used.
+* The expires value is the number of seconds for while this token is valid. If you request the offline_access permission, expires will be blank and the token is valid forever.
+
+== Flickr
+
+1. Log in to Flickr.
+1. Go to http://www.flickr.com/services/apps/create/apply/ to register for API keys.
+1. Fill out the forms to create a new app.
+1. Once you're done, find the "edit authentication flow" page ({www.flickr.com/services/apps/YOUR_FLICKR_APP_ID/auth/}[www.flickr.com/services/apps]) and
+   set the Callback URL to <your root url>/meal_ticket/flickr_callback
+
+Create global constants that look something like this:
+
+  FLICKR_TOKEN = "3637b1e30ae90503fedf9aaca8a4c370"
+  FLICKR_SECRET = "3570d29a7a3c086b"
+  FLICKR_CALLBACK = "path/to/my/flickr/callback"  # whatever URL you've created to grab the user data and do something useful
+
+Now, redirect users to flickr_auth_url, passing the permission level you want to ask for. Like so:
+
+  # For a full list of permissions, see https://developers.facebook.com/docs/authentication/permissions/
+  redirect_to flickr_auth_url("write")
+
+After they authenticate, they'll be redirected to your +FACEBOOK_CALLBACK+ method with params like:
+
+  ?flickr[token]=q2jf89ojq.j32f|FQf9j23la&facebook[user_id]=
+   - or, more legibly: -
+  {:flickr => {:token => "3215562516a046266-919fd54999d6e104", :user_id => "27934656@N00"}}
+
+Notes:
+
+* _nothing_ _to_ _note_
 
 == Contributing to meal_ticket
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it