Add annotations (in this PR limited to subscribe only to support Chat SDK reactions - ably/ably-chat-swift#293).

Reference implementation - ably/ably-js#1953
Docstrings - ably/specification#292

Annotation subscription (both summary and raw) is tested in ably/ably-chat-swift#293 (see integration test).

Author: maratal

Ably.xcodeproj/project.pbxproj

@@ -0,0 +1,104 @@
+#import "ARTAnnotation.h"
+#import "ARTJsonEncoder.h"
+#import "ARTJsonLikeEncoder.h"
+#import "ARTBaseMessage+Private.h"
+#import "ARTNSArray+ARTFunctional.h"
+#import "ARTInternalLog.h"
+
+@implementation ARTAnnotation
+
+- (instancetype)initWithType:(NSString *)type data:(id)data {
+    if (self = [self init]) {
+        self.type = [type copy];
+        if (data) {
+            self.data = data;
+            self.encoding = @"";
+        }
+    }
+    return self;
+}
+
+- (instancetype)initWithType:(NSString *)type data:(id)data clientId:(NSString *)clientId {
+    if (self = [self initWithType:type data:data]) {
+        self.clientId = clientId;
+    }
+    return self;
+}
+
+- (NSString *)description {
+    NSMutableString *description = [[super description] mutableCopy];
+    [description deleteCharactersInRange:NSMakeRange(description.length - (description.length>2 ? 2:0), 2)];
+    [description appendFormat:@",\n"];
+    [description appendFormat:@" action: %@\n", ARTAnnotationActionToStr(self.action)];
+    [description appendFormat:@" serial: %@\n", self.serial];
+    [description appendFormat:@" messageSerial: %@\n", self.messageSerial];
+    [description appendFormat:@" type: %@\n", self.type];
+    [description appendFormat:@" name: %@\n", self.name];
+    [description appendFormat:@" count: %@\n", self.count];
+    [description appendFormat:@"}"];
+    return description;
+}
+
+- (id)copyWithZone:(NSZone *)zone {
+    ARTAnnotation *annotation = [super copyWithZone:zone];
+    annotation.action = self.action;
+    annotation.serial = self.serial;
+    annotation.messageSerial = self.messageSerial;
+    annotation.type = self.type;
+    annotation.name = self.name;
+    annotation.count = self.count;
+    return annotation;
+}
+
+- (NSInteger)messageSize {
+    // spec is not clear here, issue - https://github.com/ably/specification/issues/336
+    return [super messageSize];
+}
+
+@end
+
+@implementation ARTAnnotation (Decoding)
+
++ (instancetype)fromEncoded:(NSDictionary *)jsonObject channelOptions:(ARTChannelOptions *)options error:(NSError **)error {
+    // TODO: implement
+    return nil;
+}
+
++ (NSArray<ARTMessage *> *)fromEncodedArray:(NSArray<NSDictionary *> *)jsonArray channelOptions:(ARTChannelOptions *)options error:(NSError **)error {
+    // TODO: implement
+    return nil;
+}
+
+@end
+
+NSString *ARTAnnotationActionToStr(ARTAnnotationAction action) {
+    switch (action) {
+        case ARTAnnotationCreate:
+            return @"Create"; //0
+        case ARTAnnotationDelete:
+            return @"Delete"; //1
+    }
+    return @"Unknown";
+}
+
+#pragma mark - ARTEvent
+
+@implementation ARTEvent (AnnotationAction)
+
+- (instancetype)initWithAnnotationAction:(ARTAnnotationAction)value {
+    return [self initWithString:[NSString stringWithFormat:@"ARTAnnotation%@", ARTAnnotationActionToStr(value)]];
+}
+
++ (instancetype)newWithAnnotationAction:(ARTAnnotationAction)value {
+    return [[self alloc] initWithAnnotationAction:value];
+}
+
+- (instancetype)initWithAnnotationType:(NSString *)type {
+    return [self initWithString:[NSString stringWithFormat:@"ARTAnnotation:%@", type]];
+}
+
++ (instancetype)newWithAnnotationType:(NSString *)type {
+    return [[self alloc] initWithAnnotationType:type];
+}
+
+@end

Source/ARTAnnotation.m

@@ -57,6 +57,7 @@ - (NSString *)description {
     [description appendFormat:@" timestamp: %@,\n", self.timestamp];
     [description appendFormat:@" encoding: %@,\n", self.encoding];
     [description appendFormat:@" data: %@\n", self.data];
+    [description appendFormat:@" extras: %@\n", self.extras];
     [description appendFormat:@"}"];
     return description;
 }

Source/ARTBaseMessage.m

@@ -5,6 +5,7 @@
 #import "ARTMessage.h"
 #import "ARTPresence.h"
 #import "ARTPresenceMessage.h"
+#import "ARTAnnotation.h"
 #import "ARTProtocolMessage.h"
 #import "ARTProtocolMessage+Private.h"
 #import "ARTNSDictionary+ARTDictionaryUtil.h"
@@ -298,6 +299,7 @@ - (ARTMessage *)messageFromDictionary:(NSDictionary *)input protocolMessage:(ART
     if (operation && [operation isKindOfClass:[NSDictionary class]]) {
         message.operation = [ARTMessageOperation createFromDictionary:operation];
     }
+    message.summary = [input objectForKey:@"summary"] ?: (message.action == ARTMessageActionMessageSummary ? @{} : nil); // enforce TM2q (https://ably-real-time.slack.com/archives/C03JDBVM5MY/p1749124425224069?thread_ts=1749051904.445159&cid=C03JDBVM5MY)
 
     return message;
 }
@@ -334,7 +336,18 @@ - (ARTPresenceAction)presenceActionFromInt:(int) action
     }
     ARTLogError(_logger, @"RS:%p ARTJsonEncoder invalid ARTPresenceAction %d", _rest, action);
     return ARTPresenceAbsent;
-    
+}
+
+- (ARTAnnotationAction)annotationActionFromInt:(int)action
+{
+    switch (action) {
+        case 0:
+            return ARTAnnotationCreate;
+        case 1:
+            return ARTAnnotationDelete;
+    }
+    ARTLogError(_logger, @"RS:%p ARTJsonEncoder invalid ARTAnnotationAction %d", _rest, action);
+    return ARTAnnotationCreate;
 }
 
 - (int)intFromPresenceMessageAction:(ARTPresenceAction) action
@@ -390,6 +403,47 @@ - (NSArray *)presenceMessagesFromArray:(NSArray *)input {
     return output;
 }
 
+- (ARTAnnotation *)annotationFromDictionary:(NSDictionary *)input {
+    ARTLogVerbose(_logger, @"RS:%p ARTJsonLikeEncoder<%@>: annotationFromDictionary %@", _rest, [_delegate formatAsString], input);
+    if (![input isKindOfClass:[NSDictionary class]]) {
+        return nil;
+    }
+    ARTAnnotation *annotation = [[ARTAnnotation alloc] init];
+    annotation.id = [input artString:@"id"];
+    annotation.data = [input objectForKey:@"data"];
+    annotation.encoding = [input artString:@"encoding"];
+    annotation.clientId = [input artString:@"clientId"];
+    annotation.timestamp = [input artTimestamp:@"timestamp"];
+    annotation.connectionId = [input artString:@"connectionId"];
+
+    int action = [[input artNumber:@"action"] intValue];
+    annotation.action = [self annotationActionFromInt:action];
+    
+    annotation.name = [input artString:@"name"];
+    annotation.type = [input artString:@"type"];
+    annotation.serial = [input artString:@"serial"];
+    annotation.messageSerial = [input artString:@"messageSerial"];
+    annotation.count = [input artNumber:@"count"];
+
+    return annotation;
+}
+
+- (NSArray *)annotationsFromArray:(NSArray *)input {
+    if (![input isKindOfClass:[NSArray class]]) {
+        return nil;
+    }
+    
+    NSMutableArray *output = [NSMutableArray array];
+    for (NSDictionary *item in input) {
+        ARTAnnotation *annotation = [self annotationFromDictionary:item];
+        if (!annotation) {
+            return nil;
+        }
+        [output addObject:annotation];
+    }
+    return output;
+}
+
 - (NSDictionary *)messageToDictionary:(ARTMessage *)message {
     NSMutableDictionary *output = [NSMutableDictionary dictionary];
     if (message.id) {
@@ -765,6 +819,7 @@ - (ARTProtocolMessage *)protocolMessageFromDictionary:(NSDictionary *)input {
     NSMutableArray *messages = [[input objectForKey:@"messages"] mutableCopy];
     message.messages = [self messagesFromArray:messages protocolMessage:message];
     message.presence = [self presenceMessagesFromArray:[input objectForKey:@"presence"]];
+    message.annotations = [self annotationsFromArray:[input objectForKey:@"annotations"]];
 
     return message;
 }

Source/ARTJsonLikeEncoder.m

@@ -30,9 +30,16 @@ - (NSString *)description {
     [description deleteCharactersInRange:NSMakeRange(description.length - (description.length>2 ? 2:0), 2)];
     [description appendFormat:@",\n"];
     [description appendFormat:@" name: %@\n", self.name];
-    if (self.extras) {
-        [description appendFormat:@" extras: %@\n", self.extras];
-    }
+    [description appendFormat:@" action: %@\n", ARTMessageActionToStr(self.action)];
+    [description appendFormat:@" serial: %@\n", self.serial];
+    [description appendFormat:@" updateSerial: %@\n", self.updateSerial];
+    [description appendFormat:@" version: %@\n", self.version];
+    [description appendFormat:@" createdAt: %@\n", self.createdAt];
+    [description appendFormat:@" updatedAt: %@\n", self.updatedAt];
+    [description appendFormat:@" refType: %@\n", self.refType];
+    [description appendFormat:@" refSerial: %@\n", self.refSerial];
+    [description appendFormat:@" operation: %@\n", self.operation];
+    [description appendFormat:@" summary: %@\n", self.summary];
     [description appendFormat:@"}"];
     return description;
 }
@@ -49,6 +56,7 @@ - (id)copyWithZone:(NSZone *)zone {
     message.operation = self.operation;
     message.refType = self.refType;
     message.refSerial = self.refSerial;
+    message.summary = self.summary;
     return message;
 }
 
@@ -59,6 +67,22 @@ - (NSInteger)messageSize {
 
 @end
 
+NSString *ARTMessageActionToStr(ARTMessageAction action) {
+    switch (action) {
+        case ARTMessageActionCreate:
+            return @"Create";
+        case ARTMessageActionUpdate:
+            return @"Update";
+        case ARTMessageActionDelete:
+            return @"Delete";
+        case ARTMessageActionMeta:
+            return @"Meta";
+        case ARTMessageActionMessageSummary:
+            return @"Summary";
+    }
+    return @"Unknown";
+}
+
 @implementation ARTMessage (Decoding)
 
 + (instancetype)fromEncoded:(NSDictionary *)jsonObject channelOptions:(ARTChannelOptions *)options error:(NSError **)error {

Source/ARTMessage.m

@@ -21,6 +21,7 @@ - (id)init {
         _timestamp = nil;
         _messages = nil;
         _presence = nil;
+        _annotations = nil;
         _flags = 0;
         _error = nil;
         _connectionDetails = nil;
@@ -52,6 +53,7 @@ - (NSString *)description {
     [description appendFormat:@" flags.resumed: %@,\n", NSStringFromBOOL(self.resumed)];
     [description appendFormat:@" messages: %@\n", self.messages];
     [description appendFormat:@" presence: %@\n", self.presence];
+    [description appendFormat:@" annotations: %@\n", self.annotations];
     [description appendFormat:@" params: %@\n", self.params];
     [description appendFormat:@"}"];
     return description;
@@ -70,6 +72,7 @@ - (id)copyWithZone:(NSZone *)zone {
     pm.timestamp = self.timestamp;
     pm.messages = self.messages;
     pm.presence = self.presence;
+    pm.annotations = self.annotations;
     pm.flags = self.flags;
     pm.error = self.error;
     pm.connectionDetails = self.connectionDetails;
@@ -100,6 +103,9 @@ - (BOOL)mergeFrom:(ARTProtocolMessage *)src maxSize:(NSInteger)maxSize {
          case ARTProtocolMessagePresence:
              proposed = [self.presence arrayByAddingObjectsFromArray:src.presence];
              break;
+         case ARTProtocolMessageAnnotation:
+             proposed = [self.annotations arrayByAddingObjectsFromArray:src.annotations];
+             break;
          default:
              proposed = nil;
              return NO;
@@ -120,6 +126,9 @@ - (BOOL)mergeFrom:(ARTProtocolMessage *)src maxSize:(NSInteger)maxSize {
          case ARTProtocolMessagePresence:
              self.presence = proposed;
              return YES;
+         case ARTProtocolMessageAnnotation:
+             self.annotations = proposed;
+             return YES;
          default:
              return NO;
      }
@@ -215,6 +224,8 @@ - (ARTConnectionDetails *)getConnectionDetails {
             return @"Sync"; //16
         case ARTProtocolMessageAuth:
             return @"Auth"; //17
+        case ARTProtocolMessageAnnotation:
+            return @"Annotation"; //21
     }
 
     // Because we blindly assign the action field of a ProtocolMessage received over the wire to a variable of type ARTProtocolMessageAction, we can't rely on the compiler's exhaustive checking of switch statements for ARTProtocolMessageAction.