NewsBlur/clients/ios/Other Sources/Overshare Kit/OSKActivity.h

//
//  OSKActivity.h
//  Overshare
//
//   
//  Copyright (c) 2013 Overshare Kit. All rights reserved.
//

@import UIKit;
@import Foundation;

// ACTIVITY OPTIONS
extern NSString * const OSKActivityOption_ExcludedTypes; // NSArray of activity types (strings)
extern NSString * const OSKActivityOption_BespokeActivities; // NSArray of classes, each inheriting from OSKActivity
extern NSString * const OSKActivityOption_RequireOperations; // Passing @(YES) filters out activities that can't perform via OSKActivityOperation

// BUILT-IN ACTIVITY TYPES (Your custom OSKActivity subclasses should have their own unique types.)
extern NSString * const OSKActivityType_iOS_Twitter;
extern NSString * const OSKActivityType_iOS_Facebook;
extern NSString * const OSKActivityType_iOS_Safari;
extern NSString * const OSKActivityType_iOS_SMS;
extern NSString * const OSKActivityType_iOS_Email;
extern NSString * const OSKActivityType_iOS_CopyToPasteboard;
extern NSString * const OSKActivityType_iOS_AirDrop;
extern NSString * const OSKActivityType_iOS_ReadingList;
extern NSString * const OSKActivityType_iOS_SaveToCameraRoll;
extern NSString * const OSKActivityType_API_AppDotNet;
extern NSString * const OSKActivityType_API_500Pixels;
extern NSString * const OSKActivityType_API_Instapaper;
extern NSString * const OSKActivityType_API_Readability;
extern NSString * const OSKActivityType_API_Pocket;
extern NSString * const OSKActivityType_API_Pinboard;
extern NSString * const OSKActivityType_API_GooglePlus;
extern NSString * const OSKActivityType_URLScheme_Instagram;
extern NSString * const OSKActivityType_URLScheme_Riposte;
extern NSString * const OSKActivityType_URLScheme_Tweetbot;
extern NSString * const OSKActivityType_URLScheme_1Password_Search;
extern NSString * const OSKActivityType_URLScheme_1Password_Browser;
extern NSString * const OSKActivityType_URLScheme_Chrome;
extern NSString * const OSKActivityType_URLScheme_Omnifocus;
extern NSString * const OSKActivityType_URLScheme_Things;
extern NSString * const OSKActivityType_URLScheme_Drafts;
extern NSString * const OSKActivityType_SDK_Pocket;

@class OSKActivity;
@class OSKActivityOperation;
@class OSKApplicationCredential;
@class OSKShareableContentItem;

typedef void(^OSKActivityCompletionHandler)(OSKActivity *activity, BOOL successful, NSError *error);

typedef NS_ENUM(NSInteger, OSKAuthenticationMethod) {
    OSKAuthenticationMethod_None,
    OSKAuthenticationMethod_SystemAccounts,     // e.g. system Twitter accounts
    OSKAuthenticationMethod_ManagedAccounts,    // e.g. App.net
    OSKAuthenticationMethod_Generic,            // e.g. Pocket API
};

typedef NS_ENUM(NSInteger, OSKPublishingMethod) {
    OSKPublishingMethod_None,                           // e.g. Copy to Pasteboard
    OSKPublishingMethod_URLScheme,                      // e.g. 1Password
    OSKPublishingMethod_ViewController_System,          // e.g. Email and Messages
    OSKPublishingMethod_ViewController_Bespoke,         // Your custom, one-of-a-kind publishing view controller
    OSKPublishingMethod_ViewController_Microblogging,   // e.g. Twitter & App.net
    OSKPublishingMethod_ViewController_Blogging,        // e.g. Tumblr or WordPress
    OSKPublishingMethod_ViewController_Facebook,        // duh
    OSKPublishingMethod_ViewController_GooglePlus,        // duh
};

///--------------------------------------------------------
/// @name OSKActivity
///--------------------------------------------------------

/**
 A semi-abstract base class for all activities.
 
 @discussion `OSKActivity` is the heart and soul of Overshare Kit. For every content item type (microblogging, 
 emails, etc.) there are one or more subclasses of `OSKActivity` designed to perform an action with that content.
 
 There are a few methods in the base class that should not be overridden, but for the most part *every* method
 of `OSKActivity` should be overridden by subclasses without calling super.
 
 @warning This bears repeating: failure to override required methods in subclasses — without calling the super
 implementation — will lead to assertion failures.
 */
@interface OSKActivity : NSObject

- (instancetype)initWithContentItem:(OSKShareableContentItem *)item;

@end

///------------------------------------------
/// @name Protected Methods (Do not override)
///------------------------------------------

@interface OSKActivity (DoNotOverride)

/**
 The activity's content item.
 
 @discussion `OSKShareableContentItem` is itself an abstract base class. In practice, each
 `OSKActivity` subclass will have an appropriate `OSKShareableContentItem` subclass for this
 property.
 */
@property (strong, nonatomic, readonly) OSKShareableContentItem *contentItem;

/**
 Convenience function for getting IAP requirement status.
 
 @return Returns `YES` if the activity type requires purchase **in general**.
 
 @discussion To edit which activity types require purchase and keep track of purchase status,
 use the relevant methods on OSKActivitiesManager.

 @see OSKActivitiesManager
 */
- (BOOL)requiresPurchase;

/**
 Convenience function for getting actual IAP status.
 
 @return Returns `YES` if the activity type either a) requires purchase and has already been purchased,
 or b) does not require purchase.
 
 @discussion To edit which activity types require purchase and keep track of purchase status,
 use the relevant methods on OSKActivitiesManager.
 
 @see OSKActivitiesManager
 */
- (BOOL)isAlreadyPurchased;

/**
 Convenience method for obtaining an application credential appropriate for the activity class.
 
 @return Returns a valid credential or nil.
 
 @discussion This convenience method obtains the applicationCredential from OSKActivitiesManager.
 Not every service requires an application credential. For those that do (like Facebook
 or App.net, for example) your app must provide a credential via the `OSKActivitiesManager`'s
 `customizationsDelegate`.
 */
+ (OSKApplicationCredential *)applicationCredential;

@end

///------------------------------------------------------
/// @name Required Methods for Subclasses
///------------------------------------------------------

@interface OSKActivity (RequiredMethodsForSubclasses)

/**
 The type of `OSKShareableContentItem` that the activity can handle.
 
 @return A content item type.
 */
+ (NSString *)supportedContentItemType;

/**
 The general availability of the activity. 
 
 @return Returns `YES` if generally available.
 
 @discussion This is general availability (i.e. not authentication status or user-specified
 exclusion). Most activities will always be available. Some exceptions are AirDrop (since not
 all devices have AirDrop support), or OmniFocus (since that requires that OmniFocus be
 installed on the device).
 */
+ (BOOL)isAvailable;

/**
 Uniquely identifies the activity.
 
 @return Returns the type.
 */
+ (NSString *)activityType;

/**
 A display-ready name for the activity.
 
 @return Returns the activity name, like "Twitter".
 */
+ (NSString *)activityName;

/**
 An icon for the activity.
 
 @param idiom The current user interface idiom.
 
 @return Returns a square, non-bordered, non-translucent icon of an appropriate size.
 
 @discussion Icons should be 60x60 points on iPhone and 76x76 points on iPad.
 */
+ (UIImage *)iconForIdiom:(UIUserInterfaceIdiom)idiom;

/**
 The authentication method for the activity.
 
 @return A value from the enum `OSKAuthenticationMethod`.
 
 @discussion There are four possible values:
 
    OSKAuthenticationMethod_None
    OSKAuthenticationMethod_SystemAccounts
    OSKAuthenticationMethod_ManagedAccounts
    OSKAuthenticationMethod_Generic
 
 "None" is self explanatory. These activities do not require authentication before they can perform
 their task.
 
 "SystemAccounts" refers to accounts handled by iOS, e.g. Twitter or Facebook.
 
 "ManagedAccounts" refers to accounts managed by Overshare Kit, e.g. App.net or Instapaper, to name
 a few.
 
 "Generic" refers to forms of authentication that can't be managed by either iOS or Overshare. At this
 time, the only example is `OSKPocketActivity`, which uses the Pocket SDK to opaquely authenticate the user.
 
 */
+ (OSKAuthenticationMethod)authenticationMethod;

/**
 Determines whether the activity requires an application-level credential to perform its tasks.
 
 @return Returns `YES` if the activity requires an application credential.
 
 @discussion Some services require application-specific credentials in order to authenticate the user.
 These include application keys and secrets for Oauth token generation, or the application ID for 
 sending Facebook posts.
 
 @see OSKActivitiesManager
 @see OSKApplicationCredential
 */
+ (BOOL)requiresApplicationCredential;

/**
 Determines the type of publishing view controller the activity needs to perform its task.
 
 @return Returns a value from the enum `OSKpublishingMethod`
 */
+ (OSKPublishingMethod)publishingMethod;

/**
 Determines whether or not the activity is ready to perform.
 
 @return Returns `YES` if the activity is ready.
 
 @discussion Some activities require validation of their content item properties before they're 
 ready to perform (like checking App.net post character counts). Validation might also include
 whether there is an active account (if the activitity uses accounts). 
 
 @warning This method may be called many times in a row in order to update a "Done" button
 while the user types. You should return as quickly as possible to avoid UI lags.
 */
- (BOOL)isReadyToPerform;

/**
 Triggers the activity to perform its task.
 
 @param completion A completion handler that will be called at the end of the task, whether it
 succeeds or fails.
 */
- (void)performActivity:(OSKActivityCompletionHandler)completion;

/**
 Determines whether an activity can perform via a planned `OSKActivityOperation` object.
 
 @return Returns `NO`.
 
 @warning As of this writing, `OSKActivityOperation` does not yet exist. All built-in activities
 return `NO` for this method.
 */
+ (BOOL)canPerformViaOperation;

/**
 Creates an `OSKActivityOperation` instance configured to perform the current task.
 
 @param completion A completion handler that will be called at the end of the task, whether it
 succeeds or fails.
 
 @return A fully configured `OSKActivityOperation`. As of this writing, this method will always return `nil`.
 
 @warning As of this writing, `OSKActivityOperation` does not yet exist. All built-in activities
 return `nil` for this method.
 */
- (OSKActivityOperation *)operationForActivityWithCompletion:(OSKActivityCompletionHandler)completion;

@end

///------------------------------------------------------
/// @name Optional Methods for Subclasses
///------------------------------------------------------

@interface OSKActivity (OptionalMethodsForSubclasses)

/**
 A settings icon for the activity.
 
 @return Returns a 29x29 point square, non-translucent icon.
 */
+ (UIImage *)settingsIcon;

@end;