Skip to content

Commit 59b42e9

Browse files
SimonWoolfSimonWoolf
authored
Merge pull request #292 from ably/annotations
Support annotations
2 parents 1119079 + 325faed commit 59b42e9

3 files changed

Lines changed: 301 additions & 13 deletions

File tree

‎textile/api-docstrings.md‎

Lines changed: 141 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -621,9 +621,106 @@ Enumerates the possible types of `Message` there can be.
621621
| MESSAGE_CREATE | TM5 | A normal message that has been published by a user. |
622622
| MESSAGE_UPDATE | TM5 | An update that modifies a previously-published message (referenced by `serial`). |
623623
| MESSAGE_DELETE | TM5 | A deletion of a previously-published message (referenced by `serial`). |
624-
| META_OCCUPANCY | TM5 | Channel metadata containing information on what the current occupancy of the channel is. |
624+
| META | TM5 | A meta-message (a message originating from ably rather than being explicitly published on a channel), containing information such as inband channel occupancy events that has been requested by channel param. |
625625
| MESSAGE_SUMMARY | TM5 | A message containing the latest rolled-up summary of annotations that have been made to this message. |
626626

627+
## class RestAnnotations
628+
629+
630+
Functionality for annotating messages with small pieces of data, such as emoji reactions, that the server will roll up into the message as a summary.
631+
632+
| Method / Property | Parameter | Returns | Spec | Description |
633+
|---|---|---|---|---|
634+
| publish(message: Message, annotation: OutboundAnnotation) => io ||| RSAN1 | Publish a new annotation for a message. |
635+
|| `message` || RSAN1a1 | The message to annotate. |
636+
|| `annotation` || RSAN1a2 | The annotation to publish. (Must include at least the `type`. Assumed to be an annotation.create if no action is specified) |
637+
| publish(messageSerial: string, annotation: OutboundAnnotation) => io ||| RSAN1 | Publish a new annotation for a message (alternative form where you only have the serial of the message, not a complete Message object) |
638+
|| `messageSerial` || RSAN1a | The serial field of the message to annotate. |
639+
|| `annotation` || RSAN1a2 | The annotation to publish. (Must include at least the `type`. Assumed to be an annotation.create if no action is specified) |
640+
| delete(message: Message, annotation: OutboundAnnotation) => io ||| RSAN2 | Delete an annotation for a message. |
641+
|| `message` || RSAN2a | The message to remove the annotation from. |
642+
|| `annotation` || RSAN2a | The annotation to delete. (Must include at least the `type`.) |
643+
| delete(messageSerial: string, annotation: OutboundAnnotation) => io ||| RSAN2 | Delete an annotation for a message (alternative form where you only have the serial of the message, not a complete Message object) |
644+
|| `messageSerial` || RSAN2a | The serial field of the message to remove the annotation from. |
645+
|| `annotation` || RSAN2a | The annotation to delete. (Must include at least the `type`.) |
646+
| get(message: Message, params?: `Dict<string, stringifiable>`) => io `PaginatedResult<Annotation>` ||| RSAN3 | Get all annotations for a given message (as a paginated result) |
647+
|| `message` || RSAN3a | The message to get annotations for. |
648+
|| `params` || RSAN3a | Restrictions on which annotations to get (in particular a limit) |
649+
||| `PaginatedResult<Annotation>` || A paginated result containing annotations. |
650+
| get(messageSerial: string, params?: `Dict<string, stringifiable>`) => io `PaginatedResult<Annotation>` ||| RSAN3 | Get all annotations for a given message (as a paginated result) (alternative form where you only have the serial of the message, not a complete Message object) |
651+
|| `messageSerial` || RSAN3a | The `serial` of the message to get annotations for. |
652+
|| `params` || RSAN3a | Restrictions on which annotations to get (in particular a limit) |
653+
||| `PaginatedResult<Annotation>` || A paginated result containing annotations. |
654+
655+
## class RealtimeAnnotations
656+
657+
| Method / Property | Parameter | Returns | Spec | Description |
658+
|---|---|---|---|---|
659+
| publish(message: Message, annotation: OutboundAnnotation) => io ||| RTAN1 | Publish a new annotation for a message. |
660+
|| `message` || RTAN1a | The message to annotate. |
661+
|| `annotation` || RTAN1a | The annotation to publish. (Must include at least the `type`. Assumed to be an annotation.create if no action is specified) |
662+
| publish(messageSerial: string, annotation: OutboundAnnotation) => io ||| RTAN1 | Publish a new annotation for a message (alternative form where you only have the serial of the message, not a complete Message object) |
663+
|| `messageSerial` || RTAN1a | The serial field of the message to annotate. |
664+
|| `annotation` || RTAN1a | The annotation to publish. (Must include at least the `type`. Assumed to be an annotation.create if no action is specified) |
665+
| delete(message: Message, annotation: OutboundAnnotation) => io ||| RTAN2 | Delete an annotation for a message. |
666+
|| `message` || RTAN2a | The message to remove the annotation from. |
667+
|| `annotation` || RTAN2a | The annotation to delete. (Must include at least the `type`.) |
668+
| delete(messageSerial: string, annotation: OutboundAnnotation) => io ||| RTAN2 | Delete an annotation for a message (alternative form where you only have the serial of the message, not a complete Message object) |
669+
|| `messageSerial` || RTAN2a | The serial field of the message to remove the annotation from. |
670+
|| `annotation` || RTAN2a | The annotation to delete. (Must include at least the `type`.) |
671+
| get(message: Message, params?: `Dict<string, stringifiable>`) => io `PaginatedResult<Annotation>` ||| RTAN3 | Get all annotations for a given message (as a paginated result) |
672+
|| `message` || RTAN3a | The message to get annotations for. |
673+
|| `params` || RTAN3a | Restrictions on which annotations to get (such as a `limit` on the size of the result page) |
674+
||| `PaginatedResult<Annotation>` || A paginated result containing annotations. |
675+
| get(messageSerial: string, params?: `Dict<string, stringifiable>`) => io `PaginatedResult<Annotation>` ||| RTAN3 | Get all annotations for a given message (as a paginated result) (alternative form where you only have the serial of the message, not a complete Message object) |
676+
|| `messageSerial` || RTAN3a | The `serial` of the message to get annotations for. |
677+
|| `params` || RTAN3a | Restrictions on which annotations to get (in particular a limit) |
678+
||| `PaginatedResult<Annotation>` || A paginated result containing annotations. |
679+
| subscribe((Annotation) ->)) => io ||| RTAN4 | Registers a listener that is called each time an Annotation is received on the channel. Note that if you want to receive individual realtime annotations (instead of just the rolled-up summaries), you will need to request the ANNOTATION_SUBSCRIBE ChannelMode in ChannelOptions, since they are not delivered by default. In general, most clients will not bother with subscribing to individual annotations, and will instead just look at the summary updates. |
680+
|| `listener` || RTAN4a | An event listener function. |
681+
| subscribe(String \| [String], listener?: (Annotation) ->)) => io ||| RTAN4 | Registers a listener that is called each time an Annotation matching a given type is received on the channel. Note that if you want to receive individual realtime annotations (instead of just the rolled-up summaries), you will need to request the annotation_subscribe ChannelMode in ChannelOptions, since they are not delivered by default. In general, most clients will not bother with subscribing to individual annotations, and will instead just look at the summary updates. |
682+
|| `type` || RTAN4b | A specific type string or an array of them to register the listener for. |
683+
|| `listener` || RTAN4a | An event listener function. |
684+
| unsubscribe() ||| RTAN5 | Deregisters all listeners currently receiving Annotation for the channel. |
685+
| unsubscribe(listener: (Annotation) ->)) ||| RTAN5 | Deregisters a specific listener that is registered to receive Annotation on the channel. |
686+
|| `listener` || RTAN5a | An event listener function. |
687+
| unsubscribe(String \| [String]) ||| RTAN5 | Deregisters any listener that is registered to receive Annotation on the channel for a specific type. |
688+
|| `type` || RTAN5a | A specific annotation type (or array of types) to deregister the listeners for. |
689+
| unsubscribe(String \| [String], listener: (Annotation) ->)) ||| RTAN5 | Deregisters a specific listener that is registered to receive Annotation on the channel for a given type. |
690+
|| `type` || RTAN5a | A specific annotation type (or array of types) to deregister the listener for. |
691+
|| `listener` || RTAN5a | An event listener function. |
692+
693+
## Class Annotation
694+
695+
| Property | Type | Spec | Description |
696+
|---|---|---|---|
697+
| id | string | TAN2a | An ID assigned (by the publisher or Ably) to this annotation, which is used as the idempotency key. |
698+
| action | AnnotationAction | TAN2b | The action, whether this is an annotation being added or removed, one of the AnnotationAction enum values. |
699+
| clientId | string? | TAN2c | The client ID of the publisher of this annotation (if any). |
700+
| name | string? | TAN2d | The name of this annotation. This is the field that most annotation aggregations will operate on. For example, using "distinct.v1" aggregation (specified in the type), the message summary will show a list of clients who have published an annotation with each distinct annotation.name. |
701+
| count | number? | TAN2e | An optional count, only relevant to certain aggregation methods, see aggregation methods documentation for more info. |
702+
| data | any? | TAN2f | An arbitrary publisher-provided payload, if provided. Not aggregated. |
703+
| encoding | string? | TAN2g | The encoding of the payload; typically empty as the data is decoded client-side back into the original data type. |
704+
| timestamp | number | TAN2h | Timestamp of when the annotation was received by Ably, as milliseconds since the Unix epoch. |
705+
| serial | string | TAN2i | This annotation's unique serial (lexicographically totally ordered). |
706+
| messageSerial | string | TAN2j | The serial of the message (of type `MESSAGE_CREATE`) that this annotation is annotating. |
707+
| type | string | TAN2k | The type of annotation it is, typically some identifier together with an aggregation method; for example: "emoji:distinct.v1". Handled opaquely by the SDK and validated serverside. |
708+
| extras | any? | TAN2l | A JSON object for metadata and/or ancillary payloads. |
709+
710+
## Class OutboundAnnotation
711+
712+
An `Annotation` with all fields optional except the `type`.
713+
714+
## enum AnnotationAction
715+
716+
Enumerates the possible values of the `action` field of an `Annotation`
717+
718+
| Enum | Spec | Description |
719+
|---|---|---|
720+
| ANNOTATION_CREATE | TAN2b | A created annotation |
721+
| ANNOTATION_DELETE | TAN2b | A deleted annotation |
722+
723+
627724
## class ConnectionDetails
628725

629726
Contains any constraints a client should adhere to and provides additional metadata about a [`Connection`]{@link Connection}, such as if a request to [`publish()`]{@link RealtimeClient#publish} a message that exceeds the maximum message size should be rejected immediately without communicating with Ably.
@@ -660,6 +757,21 @@ Contains an individual message that is sent to, or received from, Ably.
660757
|| `JsonArray` ||| An array of `Message`-like deserialized objects. |
661758
|| `ChannelOptions` ||| A [`ChannelOptions`]{@link ChannelOptions} object. If you have an encrypted channel, use this to allow the library to decrypt the data. |
662759
||| [`Message`] || An array of [`Message`]{@link Message} objects. |
760+
| +SummaryDistinctV1(JsonObject) -> `Dict<string, SummaryClientIdList>` ||| TM7b1 | A static factory method that takes the value of one of the keys in the `Message.summary` object for the `distinct.v1` annotation type, and outputs a strongly-typed summary entry. |
761+
|| rawSummaryEntry: JsonObject ||| The value of one of the keys of the @Message.summary@. |
762+
||| summaryEntry: `Dict<string, SummaryClientIdList>` || Map of annotation name to aggregated annotations |
763+
| +SummaryUniqueV1(JsonObject) -> `Dict<string, SummaryClientIdList>` ||| TM7b2 | A static factory method that takes the value of one of the keys in the `Message.summary` object for the `unique.v1` annotation type, and outputs a strongly-typed summary entry. |
764+
|| rawSummaryEntry: JsonObject ||| The value of one of the keys of the @Message.summary@. |
765+
||| summaryEntry: `Dict<string, SummaryClientIdList>` || Map of annotation name to aggregated annotations |
766+
| +SummaryMultipleV1(JsonObject) -> `Dict<string, SummaryClientIdCounts>` ||| TM7b3 | A static factory method that takes the value of one of the keys in the `Message.summary` object for the `multiple.v1` annotation type, and outputs a strongly-typed summary entry. |
767+
|| rawSummaryEntry: JsonObject ||| The value of one of the keys of the @Message.summary@. |
768+
||| summaryEntry: `Dict<string, SummaryClientIdCounts>` || Map of annotation name to aggregated annotations |
769+
| +SummaryFlagV1(JsonObject) -> `SummaryClientIdList` ||| TM7b4 | A static factory method that takes the value of one of the keys in the `Message.summary` object for the `flag.v1` annotation type, and outputs a strongly-typed summary entry. |
770+
|| rawSummaryEntry: JsonObject ||| The value of one of the keys of the @Message.summary@. |
771+
||| summaryEntry: `SummaryClientIdList` || Aggregated annotations |
772+
| +SummaryTotalV1(JsonObject) -> `SummaryTotal` ||| TM7b5 | A static factory method that takes the value of one of the keys in the `Message.summary` object for the `total.v1` annotation type, and outputs a strongly-typed summary entry. |
773+
|| rawSummaryEntry: JsonObject ||| The value of one of the keys of the @Message.summary@. |
774+
||| summaryEntry: `SummaryTotal` || Aggregated total summary |
663775
| clientId: String? ||| RSL1g1, TM2b | The client ID of the publisher of this message. |
664776
| connectionId: String? ||| TM2c | The connection ID of the publisher of this message. |
665777
| data: Data? ||| TM2d | The message payload, if provided. |
@@ -676,6 +788,34 @@ Contains an individual message that is sent to, or received from, Ably.
676788
| createdAt: Time? ||| TM2o | The timestamp of the very first version of a given message (will differ from `timestamp` only if the message has been updated or deleted). |
677789
| operation: Operation? ||| TM2n | In the case of an updated or deleted message, this will contain metadata about the update or delete operation. |
678790
| connectionKey: String? ||| TM2h | Allows a REST client to publish a message on behalf of a Realtime client. If you set this to the [private connection key]{@link Connection.key} of a Realtime connection when publishing a message using a [`RestClient`]{@link RestClient}, the message will be published on behalf of that Realtime client. This property is only populated by a client performing a publish, and will never be populated on an inbound message. |
791+
| summary: `Dict<string, JsonObject>`? ||| TM2q | A summary of all the annotations that have been made to the message, whose keys are the `type` fields from any annotations that it includes. For summary types the SDK knows about, static factory methods on `Message` exist to parse the values into strongly-typed objects. |
792+
793+
## Class SummaryClientIdList
794+
795+
The summary entry for aggregated annotations that use the flag.v1 aggregation method; also the per-name value for some other aggregation methods.
796+
797+
| Property | Type | Description |
798+
|---|---|---|
799+
| total | number | The total number of clients who have published an annotation with this name (or type, depending on context). |
800+
| clientIds | string[] | A list of the clientIds of all clients who have published an annotation with this name (or type, depending on context). |
801+
802+
## Class SummaryClientIdCounts
803+
804+
The per-name value for the multiple.v1 aggregation method.
805+
806+
| Property | Type | Description |
807+
|---|---|---|
808+
| total | number | The sum of the counts from all clients who have published an annotation with this name |
809+
| clientIds | { [key: string]: number } | A list of the clientIds of all clients who have published an annotation with this name, and the count each of them have contributed. |
810+
811+
812+
## Class SummaryTotal
813+
814+
The summary for the total.v1 aggregation method.
815+
816+
| Property | Type | Description |
817+
|---|---|---|
818+
| total | number | The number of clients who have published an annotation of this type |
679819

680820
## class Operation
681821

0 commit comments

Comments
 (0)