Merge pull request octokit#34 from octokit/notifications

Notifications API

Author: joshaber

External/Mantle

@@ -9,6 +9,7 @@
 #import "AFNetworking.h"
 #import <ReactiveCocoa/ReactiveCocoa.h>
 
+@class OCTNotification;
 @class OCTOrganization;
 @class OCTServer;
 @class OCTTeam;
@@ -158,6 +159,11 @@ extern NSString * const OCTClientErrorHTTPStatusCodeKey;
 // point, the returned signal will send it immediately, then terminate.
 - (RACSignal *)enqueueConditionalRequestWithMethod:(NSString *)method path:(NSString *)path parameters:(NSDictionary *)parameters notMatchingEtag:(NSString *)etag resultClass:(Class)resultClass;
 
+// Behaves like
+// -enqueueConditionalRequestWithMethod:path:parameters:notMatchingEtag:resultClass:,
+// but allows a full URL to be passed in.
+- (RACSignal *)enqueueConditionalRequestWithMethod:(NSString *)method URL:(NSURL *)URL parameters:(NSDictionary *)parameters notMatchingEtag:(NSString *)etag resultClass:(Class)resultClass;
+
 @end
 
 @interface OCTClient (User)
@@ -243,10 +249,37 @@ extern NSString * const OCTClientErrorHTTPStatusCodeKey;
 // the latest data matches `etag`, the call does not count toward the API rate
 // limit.
 //
-// Returns a signal which will send zero or more OCTEvents if new data was
-// downloaded. Unrecognized events will be omitted from the result. On success,
-// the signal will send completed regardless of whether there was new data. If
-// no `user` is set, the signal will error immediately.
+// Returns a signal which will send zero or more OCTResponses (of OCTEvents) if
+// new data was downloaded. Unrecognized events will be omitted from the result.
+// On success, the signal will send completed regardless of whether there was
+// new data. If no `user` is set, the signal will error immediately.
 - (RACSignal *)fetchUserEventsNotMatchingEtag:(NSString *)etag;
 
 @end
+
+@interface OCTClient (Notifications)
+
+// Conditionally fetch unread notifications for the user. If the latest data
+// matches `etag`, the call does not count toward the API rate limit.
+//
+// etag        - An Etag from a previous request, used to avoid downloading
+//               unnecessary data.
+// includeRead - Whether to include notifications that have already been read.
+// since       - If not nil, only notifications updated after this date will be
+//               included.
+//
+// Returns a signal which will zero or more OCTResponses (of OCTNotifications)
+// if new data was downloaded. On success, the signal will send completed
+// regardless of whether there was new data. If the client is not
+// `authenticated`, the signal will error immediately.
+- (RACSignal *)fetchNotificationsNotMatchingEtag:(NSString *)etag includeReadNotifications:(BOOL)includeRead updatedSince:(NSDate *)since;
+
+// Mark the notification has having been read.
+//
+// notification - The notification to mark as read. Cannot be nil.
+//
+// Returns a signal which will send completed on success. If the client is not
+// `authenticated`, the signal will error immediately.
+- (RACSignal *)markNotificationAsRead:(OCTNotification *)notification;
+
+@end

OctoKit.xcodeproj/project.pbxproj

@@ -7,6 +7,7 @@
 //
 
 #import "OCTClient.h"
+#import "NSDateFormatter+OCTFormattingAdditions.h"
 #import "OCTEvent.h"
 #import "OCTObject+Private.h"
 #import "OCTOrganization.h"
@@ -16,6 +17,7 @@
 #import "OCTServer.h"
 #import "OCTTeam.h"
 #import "OCTUser.h"
+#import "OCTNotification.h"
 
 NSString * const OCTClientErrorDomain = @"OCTClientErrorDomain";
 const NSInteger OCTClientErrorAuthenticationFailed = 666;
@@ -47,8 +49,8 @@ + (NSError *)authenticationRequiredError;
 //
 // method       - The HTTP method to use.
 // relativePath - The path to fetch, relative to the user object. For example,
-//				  to request `user/orgs` or `users/:user/orgs`, simply pass in
-//				  `orgs`.
+//                to request `user/orgs` or `users/:user/orgs`, simply pass in
+//                `orgs`.
 // parameters   - HTTP parameters to encode and send with the request.
 // resultClass  - The class that response data should be returned as.
 //
@@ -57,6 +59,17 @@ + (NSError *)authenticationRequiredError;
 // will error immediately.
 - (RACSignal *)enqueueUserRequestWithMethod:(NSString *)method relativePath:(NSString *)relativePath parameters:(NSDictionary *)parameters resultClass:(Class)resultClass;
 
+// Creates a request.
+//
+// method - The HTTP method to use in the request (e.g., "GET" or "POST").
+// path   - The path to request, relative to the base API endpoint. This path
+//          should _not_ begin with a forward slash.
+// etag   - An ETag to compare the server data against, previously retrieved
+//          from an instance of OCTResponse.
+//
+// Returns a request which can be modified further before being enqueued.
+- (NSMutableURLRequest *)requestWithMethod:(NSString *)method path:(NSString *)path parameters:(NSDictionary *)parameters notMatchingEtag:(NSString *)etag;
+
 @end
 
 @implementation OCTClient
@@ -102,6 +115,27 @@ - (id)initWithServer:(OCTServer *)server {
 	return self;
 }
 
+#pragma mark Request Creation
+
+- (NSMutableURLRequest *)requestWithMethod:(NSString *)method path:(NSString *)path parameters:(NSDictionary *)parameters notMatchingEtag:(NSString *)etag {
+	NSParameterAssert(method != nil);
+
+	parameters = [parameters mtl_dictionaryByAddingEntriesFromDictionary:@{
+		@"per_page": @100
+	}];
+	
+	NSMutableURLRequest *request = [self requestWithMethod:method path:[path stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding] parameters:parameters];
+
+	if (etag != nil) {
+		[request setValue:etag forHTTPHeaderField:@"If-None-Match"];
+	} else {
+		// Ignore cache data so we definitely re-fetch from the server.
+		request.cachePolicy = NSURLRequestReloadIgnoringLocalCacheData;
+	}
+
+	return request;
+}
+
 #pragma mark Request Enqueuing
 
 - (RACSignal *)enqueueRequestWithMethod:(NSString *)method path:(NSString *)path parameters:(NSDictionary *)parameters resultClass:(Class)resultClass {
@@ -116,21 +150,18 @@ - (RACSignal *)enqueueConditionalRequestWithMethod:(NSString *)method path:(NSSt
 }
 
 - (RACSignal *)enqueueConditionalRequestWithMethod:(NSString *)method path:(NSString *)path parameters:(NSDictionary *)parameters notMatchingEtag:(NSString *)etag resultClass:(Class)resultClass fetchAllPages:(BOOL)fetchAllPages {
-	NSParameterAssert(method != nil);
+	NSURLRequest *request = [self requestWithMethod:method path:path parameters:parameters notMatchingEtag:etag];
+	return [self enqueueRequest:request resultClass:resultClass fetchAllPages:fetchAllPages];
+}
 
-	parameters = [parameters mtl_dictionaryByAddingEntriesFromDictionary:@{
-		@"per_page": @100
-	}];
-	
-	NSMutableURLRequest *request = [self requestWithMethod:method path:[path stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding] parameters:parameters];
-	if (etag != nil) {
-		[request setValue:etag forHTTPHeaderField:@"If-None-Match"];
-	} else {
-        // ignore cache data so we definitely re-fatch from the server
-        request.cachePolicy = NSURLRequestReloadIgnoringLocalCacheData;
-    }
+- (RACSignal *)enqueueConditionalRequestWithMethod:(NSString *)method URL:(NSURL *)URL parameters:(NSDictionary *)parameters notMatchingEtag:(NSString *)etag resultClass:(Class)resultClass {
+	NSMutableURLRequest *request = [self requestWithMethod:method path:@"" parameters:parameters notMatchingEtag:etag];
+	request.URL = URL;
+	return [self enqueueRequest:request resultClass:resultClass fetchAllPages:YES];
+}
 
-	return [self enqueueRequest:request resultClass:resultClass fetchAllPages:fetchAllPages];
+- (RACSignal *)enqueueRequest:(NSURLRequest *)request resultClass:(Class)resultClass {
+	return [self enqueueRequest:request resultClass:resultClass fetchAllPages:YES];
 }
 
 - (RACSignal *)enqueueRequest:(NSURLRequest *)request resultClass:(Class)resultClass fetchAllPages:(BOOL)fetchAllPages {
@@ -503,3 +534,32 @@ - (RACSignal *)fetchUserEventsNotMatchingEtag:(NSString *)etag {
 }
 
 @end
+
+@implementation OCTClient (Notifications)
+
+- (RACSignal *)fetchNotificationsNotMatchingEtag:(NSString *)etag includeReadNotifications:(BOOL)includeRead updatedSince:(NSDate *)since {
+	if (!self.authenticated) return [RACSignal error:self.class.authenticationRequiredError];
+
+	NSMutableDictionary *parameters = [NSMutableDictionary dictionary];
+	parameters[@"all"] = @(includeRead);
+
+	if (since != nil) {
+		parameters[@"since"] = [NSDateFormatter oct_stringFromDate:since];
+	}
+
+	return [self enqueueConditionalRequestWithMethod:@"GET" path:@"notifications" parameters:parameters notMatchingEtag:etag resultClass:OCTNotification.class];
+}
+
+- (RACSignal *)markNotificationAsRead:(OCTNotification *)notification {
+	return [self patchNotification:notification withReadStatus:YES];
+}
+
+- (RACSignal *)patchNotification:(OCTNotification *)notification withReadStatus:(BOOL)read {
+	NSParameterAssert(notification != nil);
+
+	if (!self.authenticated) return [RACSignal error:self.class.authenticationRequiredError];
+
+	return [[self enqueueConditionalRequestWithMethod:@"PATCH" URL:notification.threadURL parameters:@{ @"read": @(read) } notMatchingEtag:nil resultClass:nil] ignoreElements];
+}
+
+@end

OctoKit/OCTClient.h

@@ -17,4 +17,7 @@
 // The SHA of the commit being commented upon.
 @property (nonatomic, copy, readonly) NSString *commitSHA;
 
+// The login of the user who created this comment.
+@property (nonatomic, copy, readonly) NSString *commenterLogin;
+
 @end

OctoKit/OCTClient.m

@@ -16,6 +16,7 @@ + (NSDictionary *)JSONKeyPathsByPropertyKey {
 	return [super.JSONKeyPathsByPropertyKey mtl_dictionaryByAddingEntriesFromDictionary:@{
 		@"HTMLURL": @"html_url",
 		@"commitSHA": @"commit_id",
+		@"commenterLogin": @"user.login",
 	}];
 }
 

OctoKit/OCTCommitComment.h

@@ -11,4 +11,10 @@
 // A single comment on an issue.
 @interface OCTIssueComment : OCTObject
 
+// The webpage URL for this comment.
+@property (nonatomic, copy, readonly) NSURL *HTMLURL;
+
+// The login of the user who created this comment.
+@property (nonatomic, copy, readonly) NSString *commenterLogin;
+
 @end

OctoKit/OCTCommitComment.m

@@ -10,4 +10,17 @@
 
 @implementation OCTIssueComment
 
+#pragma mark MTLJSONSerializing
+
++ (NSDictionary *)JSONKeyPathsByPropertyKey {
+	return [super.JSONKeyPathsByPropertyKey mtl_dictionaryByAddingEntriesFromDictionary:@{
+		@"HTMLURL": @"html_url",
+		@"commenterLogin": @"user.login",
+	}];
+}
+
++ (NSValueTransformer *)HTMLURLJSONTransformer {
+	return [NSValueTransformer valueTransformerForName:MTLURLValueTransformerName];
+}
+
 @end

OctoKit/OCTIssueComment.h

@@ -0,0 +1,57 @@
+//
+//  OCTNotification.h
+//  OctoKit
+//
+//  Created by Josh Abernathy on 1/22/13.
+//  Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import "OCTObject.h"
+
+@class OCTRepository;
+
+// The type of the notification.
+//
+// OCTNotificationTypeUnknown     - An unknown type of notification.
+// OCTNotificationTypeIssue       - A new issue, or a new comment on one.
+// OCTNotificationTypePullRequest - A new pull request, or a new comment on one.
+// OCTNotificationTypeCommit      - A new comment on a commit.
+typedef enum : NSUInteger {
+    OCTNotificationTypeUnknown,
+	OCTNotificationTypeIssue,
+	OCTNotificationTypePullRequest,
+	OCTNotificationTypeCommit,
+} OCTNotificationType;
+
+// A notification of some type of activity.
+@interface OCTNotification : OCTObject
+
+// The title of the notification.
+@property (nonatomic, readonly, copy) NSString *title;
+
+// The API URL to the notification's thread.
+@property (nonatomic, readonly, copy) NSURL *threadURL;
+
+// The API URL to the subject that the notification was generated for (e.g., the
+// issue or pull request).
+@property (nonatomic, readonly, copy) NSURL *subjectURL;
+
+// The API URL to the latest comment in the thread.
+//
+// If the notification does not represent a comment, this will be the same as
+// the subjectURL.
+@property (nonatomic, readonly, copy) NSURL *latestCommentURL;
+
+// The notification type.
+@property (nonatomic, readonly, assign) OCTNotificationType type;
+
+// The repository to which the notification belongs.
+@property (nonatomic, readonly, strong) OCTRepository *repository;
+
+// The date on which the notification was last updated.
+@property (nonatomic, readonly, strong) NSDate *lastUpdatedDate;
+
+// Whether this notification has yet to be read.
+@property (nonatomic, readonly, getter = isUnread) BOOL unread;
+
+@end

OctoKit/OCTIssueComment.m

@@ -0,0 +1,76 @@
+//
+//  OCTNotification.m
+//  OctoKit
+//
+//  Created by Josh Abernathy on 1/22/13.
+//  Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import "OCTNotification.h"
+#import "NSValueTransformer+OCTPredefinedTransformerAdditions.h"
+#import "OCTRepository.h"
+
+@implementation OCTNotification
+
+#pragma mark MTLModel
+
++ (NSDictionary *)JSONKeyPathsByPropertyKey {
+	return [super.JSONKeyPathsByPropertyKey mtl_dictionaryByAddingEntriesFromDictionary:@{
+		@"title": @"subject.title",
+		@"threadURL": @"url",
+		@"subjectURL": @"subject.url",
+		@"latestCommentURL": @"subject.latest_comment_url",
+		@"type": @"subject.type",
+		@"repository": @"repository",
+		@"lastUpdatedDate": @"updated_at",
+	}];
+}
+
++ (NSValueTransformer *)objectIDJSONTransformer {
+	return [MTLValueTransformer transformerWithBlock:^ id (id num) {
+		if ([num isKindOfClass:NSString.class]) {
+			return num;
+		} else if ([num isKindOfClass:NSNumber.class]) {
+			return [num stringValue];
+		} else {
+			return nil;
+		}
+	}];
+}
+
++ (NSValueTransformer *)threadURLJSONTransformer {
+	return [NSValueTransformer valueTransformerForName:MTLURLValueTransformerName];
+}
+
++ (NSValueTransformer *)subjectURLJSONTransformer {
+	return [NSValueTransformer valueTransformerForName:MTLURLValueTransformerName];
+}
+
++ (NSValueTransformer *)latestCommentURLJSONTransformer {
+	return [NSValueTransformer valueTransformerForName:MTLURLValueTransformerName];
+}
+
++ (NSValueTransformer *)repositoryJSONTransformer {
+	return [MTLValueTransformer mtl_JSONDictionaryTransformerWithModelClass:OCTRepository.class];
+}
+
++ (NSValueTransformer *)lastUpdatedDateJSONTransformer {
+	return [NSValueTransformer valueTransformerForName:OCTDateValueTransformerName];
+}
+
++ (NSValueTransformer *)typeJSONTransformer {
+	NSDictionary *typesByName = @{
+		@"Issue": @(OCTNotificationTypeIssue),
+		@"PullRequest": @(OCTNotificationTypePullRequest),
+		@"Commit": @(OCTNotificationTypeCommit),
+	};
+
+	return [MTLValueTransformer
+		reversibleTransformerWithForwardBlock:^(NSString *name) {
+			return typesByName[name] ?: @(OCTNotificationTypeUnknown);
+		} reverseBlock:^(NSNumber *type) {
+			return [typesByName allKeysForObject:type].lastObject;
+		}];
+}
+
+@end

OctoKit/OCTNotification.h

@@ -17,4 +17,7 @@
 // The API URL for the pull request upon which this comment appears.
 @property (nonatomic, copy, readonly) NSURL *pullRequestAPIURL;
 
+// The login of the user who created this comment.
+@property (nonatomic, copy, readonly) NSString *commenterLogin;
+
 @end

OctoKit/OCTNotification.m

@@ -16,6 +16,7 @@ + (NSDictionary *)JSONKeyPathsByPropertyKey {
 	return [super.JSONKeyPathsByPropertyKey mtl_dictionaryByAddingEntriesFromDictionary:@{
 		@"HTMLURL": @"_links.html.href",
 		@"pullRequestAPIURL": @"_links.pull_request.href",
+		@"commenterLogin": @"user.login",
 	}];
 }