diff --git a/textile/api-docstrings.md b/textile/api-docstrings.md index b00a3652..d7e1ee67 100644 --- a/textile/api-docstrings.md +++ b/textile/api-docstrings.md @@ -286,6 +286,22 @@ Enables messages to be published and historic messages to be retrieved for a cha || `data` ||| The payload of the message. | | setOptions(options: ChannelOptions) => io ||| RSL7 | Sets the [`ChannelOptions`]{@link ChannelOptions} for the channel. | || `options` ||| A [`ChannelOptions`]{@link ChannelOptions} object. | +| getMessage(serialOrMsg: String \| Message) => io Message ||| RSL11 | Retrieves the latest version of a specific message by its serial identifier or by providing a [`Message`]{@link Message} object containing the serial (which will not be mutated). | +|| `serialOrMsg` ||| Either the serial identifier string of the message to retrieve, or a [`Message`]{@link Message} object containing a populated `serial` field. | +||| `Message` || A [`Message`]{@link Message}, the latest version of the message | +| updateMessage(Message, operation?: MessageOperation, params?: `Dict`) => io Message ||| RSL12 | Publishes an update to existing message with patch semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Note that this publishes an update, it does not mutate the original message if passed in. | +|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field and the fields to update. | +|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the update operation. | +|| `params` ||| Optional parameters sent as part of the query string. | +||| `Message` || A [`Message`]{@link Message} object containing the updated message. | +| deleteMessage(Message, operation?: MessageOperation, params?: `Dict`) => io ||| RSL13 | Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses patch semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged (meaning that if you for example want the `MESSAGE_DELETE` to have an empty data, you should explicitly set the `data` to an empty object). | +|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field. | +|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the delete operation. | +|| `params` ||| Optional parameters sent as part of the query string. | +| getMessageVersions(serialOrMsg: String \| Message, params?: `Dict`) => io `PaginatedResult` ||| RSL14 | Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. | +|| `serialOrMsg` ||| Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`]{@link Message} object containing a populated `serial` field. | +|| `params` ||| Optional parameters sent as part of the query string. | +||| `PaginatedResult` || A [`PaginatedResult`]{@link PaginatedResult} object containing an array of [`Message`]{@link Message} objects representing all versions of the message. | | push: PushChannel ||| RSH4 | A [`PushChannel`]{@link PushChannel} object. | ## class RealtimeChannel @@ -351,6 +367,22 @@ Enables messages to be published and subscribed to. Also enables historic messag || `(Message)` ||| An event listener function. | | setOptions(options: ChannelOptions) => io ||| RTL16 | Sets the [`ChannelOptions`]{@link ChannelOptions} for the channel. An optional callback may be provided to notify of the success or failure of the operation. | || `options` ||| A [`ChannelOptions`]{@link ChannelOptions} object. | +| getMessage(serialOrMsg: String \| Message) => io Message ||| RTL28 | Retrieves the latest version of a specific message by its serial identifier or by providing a [`Message`]{@link Message} object containing the serial. | +|| `serialOrMsg` ||| Either the serial identifier string of the message to retrieve, or a [`Message`]{@link Message} object containing a populated `serial` field. | +||| `Message` || A [`Message`]{@link Message}, the latest version of the message | +| updateMessage(Message, operation?: MessageOperation, params?: `Dict`) => io Message ||| RTL29 | Updates an existing message with patch semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Note that this publishes an update, it does not mutate the original message if passed in. | +|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field and the fields to update. | +|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the update operation. | +|| `params` ||| Optional parameters sent as part of the query string. | +||| `Message` || A [`Message`]{@link Message} object containing the updated message. | +| deleteMessage(Message, operation?: MessageOperation, params?: `Dict`) => io ||| RTL30 | Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses patch semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged (meaning that if you for example want the `MESSAGE_DELETE` to have an empty data, you should explicitly set the `data` to an empty object). | +|| `Message` ||| A [`Message`]{@link Message} object containing a populated `serial` field. | +|| `operation` ||| An optional [`MessageOperation`]{@link MessageOperation} object containing metadata about the delete operation. | +|| `params` ||| Optional parameters sent as part of the query string. | +| getMessageVersions(serialOrMsg: String \| Message, params?: `Dict`) => io `PaginatedResult` ||| RTL31 | Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. | +|| `serialOrMsg` ||| Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`]{@link Message} object containing a populated `serial` field. | +|| `params` ||| Optional parameters sent as part of the query string. | +||| `PaginatedResult` || A [`PaginatedResult`]{@link PaginatedResult} object containing an array of [`Message`]{@link Message} objects representing all versions of the message. | ## class MessageFilterObject @@ -364,6 +396,16 @@ Contains properties to filter messages with when calling [`subscribe()`]{@link R | name: string ||| RTL22a | Filters messages by a specific message `name`. | | clientId: string ||| RTL22a | Filters messages by a specific message `clientId`. | +## class MessageOperation + +Contains metadata about a message update or delete operation. + +| Method / Property | Parameter | Returns | Spec | Description | +|---|---|---|---|---| +| clientId?: String ||| MOP2a | Optional identifier of the client performing the operation. | +| description?: String ||| MOP2b | Optional human-readable description of the operation. | +| metadata?: `Dict` ||| MOP2c | Optional dictionary of key-value pairs containing additional metadata about the operation. | + ## class ChannelProperties Describes the properties of the channel state. diff --git a/textile/features.textile b/textile/features.textile index 76da10b7..ac17c6c3 100644 --- a/textile/features.textile +++ b/textile/features.textile @@ -381,6 +381,38 @@ h3(#rest-channel). RestChannel * @(RSL8)@ @RestChannel#status@ function: makes a http get request to @/channels/@ where @@ represents the current rest host as described by "@RSC11@":#RSC11 ** @(RSL8a)@ Returns a @ChannelDetails@ object * @(RSL10)@ @RestChannel#annotations@ attribute contains the @RestAnnotations@ object for this channel +* @(RSL11)@ @RestChannel#getMessage@ function: +** @(RSL11a)@ Takes a first argument of a @serial@ string of the message to be retrieved. +*** @(RSL11a1)@ In languages where method overloading is supported, the first argument should also accept a @Message@ object (which must contain a populated @serial@ field) +** @(RSL11b)@ The SDK must send a GET request to the endpoint @/channels/{channelName}/messages/{serial}@ +** @(RSL11c)@ Returns the decoded @Message@ object for the specified message serial +* @(RSL12)@ @RestChannel#updateMessage@ function: +** @(RSL12a)@ Takes a first argument of a @Message@ object (which must contain a populated @serial@ field), an optional second argument of a @MessageOperation@ object, and an optional third argument of @Dict@ publish params +** @(RSL12b)@ The SDK must send a PATCH to @/channels/{channelName}/messages/{serial}@, with any @params@ sent in the querystring. The request body consists of an object with the following fields: +*** @(RSL12b1)@ @serial@ - the serial identifier of the message being updated +*** @(RSL12b2)@ @operation@ - the @MessageOperation@ object if provided +*** @(RSL12b3)@ @name@ - the message name from the @Message@ object if provided +*** @(RSL12b4)@ @data@ - the message data from the @Message@ object if provided, encoded per @RSL4@ +*** @(RSL12b5)@ @encoding@ - the encoding field set according to @RSL4@ if @data@ was encoded +*** @(RSL12b6)@ @extras@ - the extras field from the @Message@ object if provided +** @(RSL12c)@ The body must be encoded to the appropriate format per @RSC8@ +** @(RSL12d)@ Returns the updated @Message@ object, which the server will have responded with +* @(RSL13)@ @RestChannel#deleteMessage@ function: +** @(RSL13a)@ Takes a first argument of a @Message@ object (which must contain a populated @serial@ field), an optional second argument of a @MessageOperation@ object, and an optional third argument of @Dict@ publish params +** @(RSL13b)@ The SDK must send a POST to @/channels/{channelName}/messages/{serial}/delete@, with any @params@ sent in the querystring. The request body consists of an object with the following fields: +*** @(RSL13b1)@ @serial@ - the serial identifier of the message being deleted +*** @(RSL13b2)@ @operation@ - the @MessageOperation@ object if provided +*** @(RSL13b3)@ @name@ - the message name from the @Message@ object if provided +*** @(RSL13b4)@ @data@ - the message data from the @Message@ object if provided, encoded per @RSL4@ +*** @(RSL13b5)@ @encoding@ - the encoding field set according to @RSL4@ if @data@ was encoded +*** @(RSL13b6)@ @extras@ - the extras field from the @Message@ object if provided +** @(RSL13c)@ The body must be encoded to the appropriate format per @RSC8@ +** @(RSL13d)@ Returns the updated (well, 'deleted') @Message@ object, which the server will have responded with +* @(RSL14)@ @RestChannel#getMessageVersions@ function: +** @(RSL14a)@ Takes a first argument a @serial@ string of the message whose versions are to be retrieved, and an optional second argument of @Dict@ params +*** @(RSL14a1)@ In languages where method overloading is supported, the first argument should also accept a @Message@ object (which must contain a populated @serial@ field) +** @(RSL14b)@ The SDK must send a GET request to the endpoint @/channels/{channelName}/messages/{serial}/versions@ +** @(RSL14c)@ Returns a @PaginatedResult@ h3(#plugins). Plugins * @(PC1)@ Specific client library features that are not commonly used may be supplied as independent libraries, as plugins, in order to avoid excessively bloating the client library. Although such plugins are packaged as independent libraries, they are still considered logically to be part of the client library code and, as such, may be tightly coupled with the client library implementation. The client library can be assumed to be aware of the plugin specific type and capabilities, and such plugins may by design be coupled to a specific version of the client library. @@ -820,6 +852,10 @@ h3(#realtime-channel). RealtimeChannel ** @(RTL25a)@ If the channel is already in the given state, calls the listener with a `null` argument. ** @(RTL25b)@ Else, calls @#once@ with the given state and listener. * @(RTL26)@ @RealtimeChannel#annotations@ attribute contains the @RealtimeAnnotations@ object for this channel +* @(RTL28)@ @RealtimeChannel#getMessage@ function: same as @RestChannel#getMessage@ +* @(RTL29)@ @RealtimeChannel#updateMessage@ function: same as @RestChannel#updateMessage@ +* @(RTL30)@ @RealtimeChannel#deleteMessage@ function: same as @RestChannel#deleteMessage@ +* @(RTL31)@ @RealtimeChannel#getMessageVersions@ function: same as @RestChannel#getMessageVersions@ h3(#realtime-presence). RealtimePresence @@ -2449,6 +2485,11 @@ class ChannelOptions: // TB* params?: Dict // TB2c modes?: [ChannelMode] // TB2d +class MessageOperation: // MOP* + clientId?: String // MOP2a + description?: String // MOP2b + metadata?: Dict // MOP2c + class DeriveOptions: // DO* filter: String // DO2a (The filter string is a valid JMESPath String Expression)