Merge pull request #2648 from ably/edu-1590-api-js-latest

[EDU-1590] Update JS API references to match latest ably-js v2 API

Author: m-hulbert

content/api/realtime-sdk.textile

@@ -3,7 +3,6 @@ title: Constructor
 meta_description: "Realtime Client Library SDK API reference section for the constructor object."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, constructor, instantiate"
 section: api
-index: 1
 languages:
   - javascript
   - nodejs
@@ -13,37 +12,12 @@ languages:
   - objc
   - csharp
   - flutter
-jump_to:
-  Constructor object:
-    - constructor
-  Attributes:
-    - auth
-    - channels
-    - client_id#client-id
-    - connection
-    - rest_client#rest-client
-  Methods:
-    - connect
-    - close
-    - stats
-    - time
-    - request
-  Related Types:
-    - ClientOptions#client-options
-    - stats#stats-type
-    - HttpPaginatedResponse#http-paginated-response
 redirect_from:
   - /docs/api/versions/v1.1/realtime-sdk
   - /docs/api/versions/v1.0/realtime-sdk
   - /docs/api/versions/v0.8/realtime-sdk
 ---
 
-blang[javascript,nodejs].
-
-  <aside data-type='note'>
-  <p>This API reference is for version 1.2 of the JavaScript SDK. Version 2.0 references are "available in TypeDoc.":https://ably.com/docs/sdk/js/v2.0/</p>
-  </aside>
-
 h2(#constructor). Constructor
 
 The Ably Realtime library constructor is overloaded allowing it to be instantiated using a "@ClientOptions@":#client-options object, or more simply using a string containing an "API key":/docs/auth/basic or "Token":/docs/auth/token, as shown below:
@@ -148,7 +122,7 @@ h6(#connect).
   csharp: Connect
 
 bq(definition).
-  default: connect()
+  default: connect(): void
   ruby:    "Deferrable":/docs/api/realtime-sdk/types#deferrable connect -> yields "@Connection@":/docs/api/realtime-sdk/connection
   java:    void connect()
   csharp:  void Connect()
@@ -169,7 +143,7 @@ h6(#close).
   csharp: Close
 
 bq(definition).
-  default: close()
+  default: close(): void
   ruby:    "Deferrable":/docs/api/realtime-sdk/types#deferrable close -> yields "@Connection@":/docs/api/realtime-sdk/connection
   java:    void close()
   csharp:  void Close()
@@ -190,13 +164,14 @@ h6(#stats).
   csharp: Stats
 
 bq(definition).
-  default: stats(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats> results))
-  ruby:    "Deferrable":/docs/api/realtime-sdk/types#deferrable stats(Hash options) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats>
-  java:    "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats> stats("Param":#param[] options)
-  swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"ARTStats":/docs/api/realtime-sdk/types#stats>?, ARTErrorInfo?) -> Void) throws
-  csharp:  Task<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":/docs/api/realtime-sdk/types#stats>> StatsAsync(StatsRequestParams query)
+  default: stats(Object options, callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type> results))
+  jsall:   stats(Object params?): Promise<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type>>
+  ruby:    "Deferrable":/docs/api/realtime-sdk/types#deferrable stats(Hash options) -> yields "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type>
+  java:    "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type> stats("Param":#param[] options)
+  swift,objc: stats(query: ARTStatsQuery?, callback: ("ARTPaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"ARTStats":#stats-type>?, ARTErrorInfo?) -> Void) throws
+  csharp:  Task<"PaginatedResult":/docs/api/realtime-sdk/types#paginated-result<"Stats":#stats-type>> StatsAsync(StatsRequestParams query)
 
-This call queries the "REST @/stats@ API":/docs/api/rest-api#stats and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result is returned, containing an array of "Stats":#stats for the first page of results. "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
+This call queries the "REST @/stats@ API":/docs/api/rest-api#stats and retrieves your application's usage statistics. A "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result is returned, containing an array of "Stats":#stats-type for the first page of results. "PaginatedResult":/docs/api/realtime-sdk/types#paginated-result objects are iterable providing a means to page through historical statistics. "See an example set of raw stats returned via the REST API":/docs/metadata-stats/stats#metrics.
 
 See "statistics":/docs/metadata-stats/stats for more information.
 
@@ -208,14 +183,20 @@ h6(#time).
 
 bq(definition).
   default: time(callback("ErrorInfo":/docs/api/realtime-sdk/types#error-info err, Number time))
-  ruby:   "Deferrable":/docs/api/realtime-sdk/types#deferrable time -> yields Time
-  java:   long time()
-  csharp: Task<DateTimeOffset> TimeAsync()
+  jsall:   time(): Promise<Number>
+  ruby:    "Deferrable":/docs/api/realtime-sdk/types#deferrable time -> yields Time
+  java:    long time()
+  csharp:  Task<DateTimeOffset> TimeAsync()
   objc,swift: time(callback: (NSDate?, NSError?) -> Void)
 
 Obtains the time from the Ably service as <span lang="ruby">a @Time@ object</span><span lang="csharp">a @DateTimeOffset@ object</span><span lang="default">milliseconds since epoch</span>. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably "TokenRequests":/docs/api/realtime-sdk/authentication#token-request with a more accurate timestamp should use the @queryTime@ "clientOptions":#client-options instead of this method).
 
-blang[jsall,objc,swift].
+blang[jsall].
+  h4. Returns
+
+  Returns a promise. On success, the promise is fulfilled with the time as milliseconds since the Unix epoch. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object.
+
+blang[objc,swift].
   h4. Callback result
 
   On success, @time@ is a number containing the number of milliseconds since the epoch.
@@ -238,7 +219,6 @@ blang[csharp].
 
   Failure to retrieve the Ably server time will raise an "@AblyException@":#ably-exception.
 
-
 blang[ruby].
   h4. Returns
 
@@ -250,6 +230,45 @@ blang[ruby].
 
 <%= partial partial_version('rest/_request') %>
 
+blang[javascript].
+  h6(#batchPublish). batchPublish
+
+  There are two overloaded versions of this method:
+
+  bq(definition#batchPublish).
+    default:  batchPublish("BatchPublishSpec":#batch-publish-spec spec): Promise<"BatchResult":#batch-result<"BatchPublishSuccessResult":#batch-publish-success-result | "BatchPublishFailureResult":#batch-publish-failure-result>>
+
+  Publishes a "@BatchPublishSpec@":#batch-publish-spec object to one or more channels, up to a maximum of 100 channels.
+
+  bq(definition#batchPublishArray).
+    default:  batchPublish("BatchPublishSpec[]":#batch-publish-spec specs): Promise<"BatchResult":#batch-result<"BatchPublishSuccessResult":#batch-publish-success-result | "BatchPublishFailureResult":#batch-publish-failure-result>[]>
+
+  Publishes one or more "@BatchPublishSpec@":#batch-publish-spec objects to one or more channels, up to a maximum of 100 channels.
+
+  h4. Parameters
+
+  - spec := an object describing the messages to be batch published and to which channels<br>__Type: "@BatchPublishSpec@":#batch-publish-spec
+  - specs := an array of objects describing the messages to be batch published and to which channels<br>__Type: "@BatchPublishSpec@[]":#batch-publish-spec
+
+  h4. Returns
+
+  Returns a promise. On success, the promise is fulfilled with a "@BatchResult@":#batch-result object, or an array of "@BatchResult@":#batch-result objects, containing information about the result of the batch publish operation for each channel. The successful results of specific channels are returned as "@BatchPublishSuccessResult@":#batch-publish-success-result objects, whilst failures are "@BatchPublishFailureResult@":#batch-publish-failure-result objects. If an array of "@BatchResult@":#batch-result objects are returned, they are in the same order as the provided "@BatchPublishSpec@":#batch-publish-spec. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object.
+
+  h6(#batchPresence). batchPresence
+
+  bq(definition#batchPresence).
+    default: batchPresence(String[] channels): Promise<"BatchResult":#batch-result<"BatchPresenceSuccessResult":#batch-presence-success-result | "BatchPresenceFailureResult":#batch-presence-failure-result>[]>
+
+  Retrieves the presence state for one or more channels, up to a maximum of 100 channels. Presence state includes the "@clientId@":#client-options of members and their current "@PresenceAction@":/docs/api/realtime-sdk/presence#presence-action.
+
+  h4. Parameters
+
+  - channels := an array of one or more channel names, up to a maximum of 100 channels<br>__Type: @String[]@__
+
+  h4. Returns
+
+  Returns a promise. On success, the promise is fulfilled with a "@BatchResult@":#batch-result object containing information about the result of the batch presence request for each channel. The successful results of specific channels are returned as "@BatchPresenceSuccessResult@":#batch-presence-success-result objects, whilst failures are "@BatchPresenceFailureResult@":#batch-presence-failure-result objects. On failure, the promise is rejected with an "@ErrorInfo@":/docs/api/realtime-sdk/types#error-info object.
+
 h2(#related-types). Related types
 
 h3(#client-options).
@@ -274,6 +293,8 @@ h3(#stats-type).
 
 h3(#stats-granularity).
   objc,swift: ARTStatsGranularity
+  jsall:      StatsIntervalGranularity
+  csharp:     StatsIntervalGranularity
 
 <%= partial partial_version('types/_stats_granularity') %>
 
@@ -287,3 +308,35 @@ h3(#param).
 
 blang[java].
   <%= partial partial_version('types/_param'), indent: 2, skip_first_indent: true %>
+
+blang[jsall].
+
+  h3(#batch-publish-spec).
+    jsall: BatchPublishSpec
+
+  <%= partial partial_version('types/_batch_publish_spec') %>
+
+  h3(#batch-result).
+    jsall: BatchResult
+
+  <%= partial partial_version('types/_batch_result') %>
+
+  h3(#batch-publish-success-result).
+    jsall: BatchPublishSuccessResult
+
+  <%= partial partial_version('types/_batch_publish_success_result') %>
+
+  h3(#batch-publish-failure-result).
+    jsall: BatchPublishFailureResult
+
+  <%= partial partial_version('types/_batch_publish_failure_result') %>
+
+  h3(#batch-presence-success-result).
+    jsall: BatchPresenceSuccessResult
+
+  <%= partial partial_version('types/_batch_presence_success_result') %>
+
+  h3(#batch-presence-failure-result).
+    jsall: BatchPresenceFailureResult
+
+  <%= partial partial_version('types/_batch_presence_failure_result') %>