Header spec for FBSession + POR for next rev iOS SDK

Summary:
This diff contains a header-spec for FBSession, as well as
a header and POR for the next rev of the sdk

Test Plan: n/a

Reviewers: mmarucheck, vijaye, gregschechte, ekoneil

Reviewed By: vijaye

Differential Revision: https://phabricator.fb.com/D424291

src/FBSession.h

@@ -0,0 +1,153 @@
+/*
+ * Copyright 2012 Facebook
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+
+// up-front decl's
+@class FBSession;
+@class FBSessionTokenCachingStrategy;
+
+// FBSessionStatus enum
+//
+// Summary:
+// Passed to handler block when a login call has completed
+typedef enum _FBSessionStatus {
+    // initial pre-valid invalid state
+    FBSessionStatusInitial              = 0,
+
+    // valid session status values
+    FBSessionStatusLoggedIn             = 1001,  
+    FBSessionStatusTokenExtended        = 1002,  
+    FBSessionStatusValidCachedToken     = 1003,
+
+    // invalid session status values
+    FBSessionStatusLoggedOut            = 1,
+    FBSessionStatusLoginFailed          = 2, // NSError obj w/more info
+    FBSessionStatusSessionInvalidated   = 3, // "
+
+} FBSessionStatus;
+
+typedef void (^FBSessionStatusCallback)(FBSession *session, 
+                                        FBSessionStatus status, 
+                                        NSError *error);
+
+// FBSession class
+//
+// Summary:
+// FBSession object is used to authenticate/authorize a user, as well
+// as to manage the related access token. An FBSession object is required
+// for all authenticated uses of FBRequest.
+// 
+// Behavior notes:
+// Instances of the FBSession class notifiy of state changes in these ways; 
+// a) callers of certain session* methods may provide a block to be called
+// back in the course of processing the single operation (e.g. login)
+// b) session instances post the "FBSessionLogin" and "FBSessionInvalid"
+// notifications, which may be observed via NSNotificationCenter
+// c) the object supports KVO for property changes
+@interface FBSession : NSObject
+
+// creating a session
+
+// session/sessionWithPermissions returns a session instance
+//
+// Summary:
+// The simplest factory method requires only an appId to initiate a session with
+// Facebook. Following are the descriptions of the arguments along with 
+// their defaults when ommitted.
+//   permissions:          - array of strings naming permissions to authorize; a 
+//                         nil value indicates access to basic information; 
+//                         default=nil
+//   appId:                - returns a session object for the given app id; nil
+//                         specifies that the appId should be pulled from the
+//                         plist; default=nil
+//   urlSchemeSuffix:      - suffix, used for cases where multiple iOS apps use 
+//                         a single appid; nil indicates the urlSchemeSuffix
+//                         should be pulled from plist; default=nil
+//   tokenCachingStrategy: - policy object for fetching and storing a cached
+//                         token value; when nil, the token and expiration date
+//                         are stored using NSUserDefaults with the names
+//                         "FBAccessTokenKey", and "FBExpirationDateKey";
+//                         default=nil
+//
+// Behavior notes: For a first cut at this, we are removing the public ability
+// to force an extension to an access token; instead we will implicitly do this
+// when requests are made. 
+- (id)init;
+
+- (id)initWithPermissions:(NSArray*)permissions;
+
+- (id)initWithAppID:(NSString*)appID
+           permissions:(NSArray*)permissions
+       urlSchemeSuffix:(NSString*)urlSchemeSuffix
+    tokenCacheStrategy:(FBSessionTokenCachingStrategy*)tokenCachingStrategy;
+
+// instance readonly properties
+@property(readonly) BOOL isValid;
+@property(readonly) FBSessionStatus status;
+@property(nonatomic, readonly) NSString *appID;
+@property(nonatomic, readonly) NSString *urlSchemeSuffix;
+@property(retain, readonly) NSString *accessToken;
+@property(retain, readonly) NSDate *expirationDate;
+@property(copy, readonly) NSArray *permissions;
+
+// instance methods
+
+// loginWithCompletionBlock logs a user on to Facebook
+//
+// Summary:
+// Login using Facebook
+//   WithCompletionBlock   - a block to call with the login result; default=nil
+- (void)loginWithCompletionBlock:(FBSessionStatusCallback)handler;
+
+// invalidate
+//
+// Summary:
+// Invalidates the local session object
+- (void)invalidate;
+
+// logout
+//
+// Summary:
+// Logout invalidates the in-memory session, and clears any persisted cache
+- (void)logout;
+
+// handleOpenURL
+//
+// Summary:
+// Helper method, used to provide an implementation for 
+// [UIApplicationDelegate application:openUrl:*] capable of updating a session
+// based on the url
+- (BOOL)handleOpenURL:(NSURL*)url;
+
+@end
+
+// FBSessionTokenCachingStrategy
+//
+// Summary:
+// Implementors execute token and expiration-date caching and fetching logic
+// for a Facebook integrated application
+@interface FBSessionTokenCachingStrategy : NSObject
+
++ (id)init;
++ (id)initWithNSUserDefaultAccessTokenKeyName:(NSString*)tokenKeyName
+                         expirationDateKeyName:(NSString*)dateKeyName;
+
+- (void)cacheToken:(NSString*)token expirationDate:(NSDate*)date;
+- (NSString*)fetchTokenAndExpirationDate:(NSDate**)date;
+- (void)clearToken:(NSString*)token;
+
+@end

src/FacebookSDK.h

@@ -0,0 +1,101 @@
+/*
+ * Copyright 2012 Facebook
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import "FBSession.h"
+
+////////////////////////////////////////////////////////////////////////////////
+
+/* 
+ Summary: this diff summarizes changes to the Facebook iOS SDK that we are
+ considering for the next few months. This is a header-only diff, and is not
+ a complete description of our thinking, but is meant to provide context
+ sufficient for review by others.
+ 
+ Files:
+ FacebookSDK.h   - this file, high-level description of the effort and goals
+ FBSession.h     - example spec for FBSession class 
+ 
+ Goals:
+ * Leverage and work well with modern features of iOS (e.g. blocks, ARC, etc.)
+ * Patterned after best of breed iOS frameworks (e.g. naming, pattern-use, etc.)
+ * Light and/or commodity integration experience is painless & easy to describe
+ * Deep support for at least one "key scenario" (e.g. publishing OG app)
+ 
+ Notes on approaches:
+ 1) We are using our key scenario (owned by Eddie O'Neil) to drive 
+    prioritization of work
+ 2) We will be building-atop/refactoring the existing iOS SDK implementation
+ 3) We have prototyped an incremental approach where we can choose to maintain
+    as little or as much compatibility with the existing SDK needed
+    3.a) and so we will be developing to this approach
+    3.b) and then at push-time we will decide when/what to break on a
+         feature by feature basis
+ 4) Some light but critical infrastructure is needed to support both the goals
+    and the execution of this change (e.g. a build/package/deploy process)
+ 
+ Design points:
+ We will move to a more object-oriented approach, in order to facilitate the
+ addition of a different class of objects, such as controls and visual helpers
+ (e.g. FBLikeView, FBPersonView), as well as sub-frameworks to enable scenarios 
+ such (e.g. FBOpenGraphEntity, FBLocalEntityCache, etc.)
+ 
+ As we add features, it will no longer be appropriate to host all functionality
+ in the Facebook class. We may (presently undecided) keep the Facebook class to 
+ aid the ultra-simple use cases, and to perhaps preserve compatibility with the 
+ existing SDK. However, it will cease to be the central design point of the 
+ and will become a lighter-weight helper class, that wraps other public objects.
+ 
+               *------------* *----------*  *----------------* *---*
+  Scenario --> |FBPersonView| |FBLikeView|  |FBLocationFinder| | F |
+               *------------* *----------*  *----------------* | a |
+               *-------------------*  *----------*  *--------* | c |
+ Component --> | FBOpenGraphEntity |  | FBDialog |  | FBView | | e |
+               *-------------------*  *----------*  *--------* | b |
+               *---------* *---------* *---------------------* | o |
+      Core --> |FBSession| |FBRequest| |Utilities (e.g. JSON)| | o |
+               *---------* *---------* *---------------------* * k *
+                                                               
+ The figure above describes three layers of functionality, with the existing
+ Facebook on the side as a helper proxy to a subset of the overal SDK. The
+ layers loosely organize the SDK into *Core Objects* necessary to interface 
+ with Facebook, higher-level *Framework Components* that feel like natural
+ extensions to existing frameworks such as UIKit and Foundation, but which
+ reuse surface broadly applicable Facebook-specific behavior, and finally the
+ *Scenario Objects*, which provide deeper turnkey capibilities for useful 
+ mobile scenarios.
+ 
+ Use example (low barrier use case):
+ 
+ // log on to Facebook
+ _fbsession = [[FBSession alloc] init];
+ [_fbsession loginWithCompletionBlock:^(FBSession *session, 
+                                        FBSessionStatus status, 
+                                        NSError *error) {
+     if (session.isValid) {
+         // request basic information for the user
+         [FBRequest requestWithGraphPath:@"me"
+                              forSession:session
+                   completeResultToBlock:^void(FBRequest *request, 
+                                               FBRequestStatus status,
+                                               id result) {
+             if (status == FBRequestStatusSuccess) {
+                 // get json from result
+             }
+         }];
+     }
+ }];
+
+*/