Merge integration/liveobjects into main

content/api/realtime-sdk/channels.textile

@@ -151,6 +151,11 @@ h6(#push).
 
 Provides access to the "PushChannel":/docs/api/realtime-sdk/push#push-channel object for this channel which can be used to access members present on the channel, or participate in presence.
 
+h6(#objects).
+  default: objects
+
+Provides access to the "Objects":/docs/liveobjects object for this channel which can be used to read, modify and subscribe to LiveObjects on a channel.
+
 h3. Methods
 
 h6(#publish).

content/auth/capabilities.textile

@@ -42,6 +42,8 @@ The following capability operations are available for API keys and issued tokens
 - subscribe := can subscribe to messages and presence state change messages on channels, and get the presence set of a channel
 - publish := can publish messages to channels
 - presence := can register presence on a channel (enter, update and leave)
+- object-subscribe := can subscribe to updates to objects on a channel
+- object-publish := can update objects on a channel
 - history := can retrieve message and presence state history on channels
 - stats := can retrieve current and historical usage statistics for an app
 - push-subscribe := can subscribe devices for push notifications

content/channels/options/index.textile

@@ -234,7 +234,7 @@ await channel.setOptions(channelOptions);
 
 h2(#params). Params
 
-The @params@ property can be used to enable additional features on a channel-by-channel basis. These features include using @rewind@ to replay messages published prior to a client attaching to a channel, @delta@ so that message payloads only contain the difference between the current and previous message, and @occupancy@ to subscribe to metrics about the clients attached to a channel.
+The @params@ property can be used to enable additional features on a channel-by-channel basis.
 
 h3(#rewind). Rewind
 
@@ -380,7 +380,9 @@ The following is an example of an occupancy metric event:
       subscribers: 1,
       presenceConnections: 1,
       presenceMembers: 0,
-      presenceSubscribers: 1
+      presenceSubscribers: 1,
+      objectPublishers: 1,
+      objectSubscribers: 1
     }
   },
   encoding: null,
@@ -402,17 +404,46 @@ Occupancy events have a payload in the @data@ property with a value of @occupanc
 }
 ```
 
+h3(#objects). Inband Objects
+
+"Inband objects":/docs/liveobjects/inband-objects allows clients to subscribe to changes to "LiveObjects":/docs/liveobjects channel objects as regular channel messages.
+
+When using inband objects, the client receives messages with the special name @[meta]objects@ that describe the current set of objects on a channel.
+
+<aside class="note">
+<p>This feature enables clients to subscribe to LiveObjects updates in realtime even on platforms that don't yet have a dedicated LiveObjects Realtime client implementation. If you're using LiveObjects from JavaScript/TypeScript, use the LiveObjects "plugin":/docs/liveobjects/quickstart?lang=javascript which has dedicated support for all LiveObjects features.</p>
+</aside>
+
+For more information see the "inband objects":/docs/liveobjects/inband-objects documentation.
+
 h2(#modes). Modes
 
-The @modes@ property can be used to set channel mode flags. Channel mode flags enable a client to specify a subset of the "capabilities":/docs/auth/capabilities granted by their token or API key. Channel mode flags offer the ability for clients to use different capabilities for different channels, however, as they are flags and not permissions they cannot be enforced by an authentication server.
+Channel mode flags enable a client to specify which functionality they will use on the channel.
+
+A client can explicitly request a set of modes using the @modes@ property. If the @modes@ property is not provided, the default modes will be used.
+
+The available set of channel mode flags are:
+
+|_. Flag |_. Description |_. Default? |
+| @SUBSCRIBE@ | Can subscribe to receive messages on the channel. | Yes |
+| @PUBLISH@ | Can publish messages to the channel. | Yes |
+| @PRESENCE_SUBSCRIBE@ | Can subscribe to receive presence events on the channel. | Yes |
+| @PRESENCE@ | Can register presence on the channel. | Yes |
+| @OBJECT_PUBLISH@ | Can update objects on the channel. | No |
+| @OBJECT_SUBSCRIBE@ | Can subscribe to receive updates to objects on the channel. | No |
+
+The set of modes available to a client is determined by the set of "capabilities":/docs/auth/capabilities granted by their token or API key.
+
+The modes granted by each capability are:
 
-The channel mode flags available are:
+|_. Capability |_. Granted Modes |
+| @subscribe@ | @SUBSCRIBE@, @PRESENCE_SUBSCRIBE@, @OBJECT_SUBSCRIBE@ |
+| @publish@ | @PUBLISH@ |
+| @presence@ | @PRESENCE@ |
+| @object-subscribe@ | @OBJECT_SUBSCRIBE@ |
+| @object-publish@ | @OBJECT_PUBLISH@ |
 
-|_. Flag |_. Description |
-| SUBSCRIBE | Can subscribe to receive messages on the channel. |
-| PUBLISH | Can publish messages to the channel. |
-| PRESENCE_SUBSCRIBE | Can subscribe to receive presence events on the channel. |
-| PRESENCE | Can register presence on the channel. |
+The actual modes assigned to a client will be the **intersection** of the requested @modes@ and the modes available to the client according to its capabilities. For example, a client with the @subscribe@ capability which explicitly requests @SUBSCRIBE@ and @PUBLISH@ modes will be assigned only the @SUBSCRIBE@ mode.
 
 The following is an example of setting channel mode flags:
 

content/channels/options/rewind.textile

@@ -41,7 +41,7 @@ If the attachment is successful, and one or more messages exist on the channel p
 Any @rewind@ value that cannot be parsed either as a number or a time specifier will cause the attachment request to fail and return an error.
 
 <aside data-type='note'>
-<p>If you have enabled the "persist last message":/docs/storage-history/storage#persist-last-message channel rule on a channel, you can attach with @rewind=1@ to retrieve the last message. Only the last message published can be stored for up to a year, and persist last message doesn't apply to presence messages.</p>
+<p>If you have enabled the "persist last message":/docs/storage-history/storage#persist-last-message channel rule on a channel, you can attach with @rewind=1@ to retrieve the last message. Only the last message published can be stored for up to a year, and persist last message doesn't apply to presence or object messages.</p>
 </aside>
 
 The following example subscribes to a channel and retrieves the most recent message sent on it, if available:

content/integrations/webhooks/index.textile

@@ -415,7 +415,9 @@ The following is an example of a batched @channel lifecycle@ payload:
             "subscribers": 1,
             "presenceConnections": 1,
             "presenceMembers": 0,
-            "presenceSubscribers": 1
+            "presenceSubscribers": 1,
+            "objectPublishers": 1,
+            "objectSubscribers": 1
           }
         }
       }

content/liveobjects/batch.textile

@@ -0,0 +1,152 @@
+---
+title: Batch operations
+meta_description: "Group multiple objects operations into a single channel message to apply grouped operations atomically and improve performance."
+product: liveobjects
+languages:
+  - javascript
+---
+
+<aside data-type='experimental'>
+<p>LiveObjects is currently Experimental. Its features are still in development and subject to rapid change.</p>
+</aside>
+
+The Batching API in LiveObjects enables multiple updates to be grouped into a single channel message and applied atomically. It ensures that all operations in a batch either succeed together or are discarded entirely. Batching operations is essential when multiple related updates to channel objects must be applied as a single atomic unit, for example, when application logic depends on multiple objects being updated simultaneously. Without batching, if one operation succeeds while another fails, your application state could become inconsistent.
+
+Note that this differs from "Message batching":/docs/messages/batch, the native Pub/Sub messages feature. The LiveObjects Batching API is a separate API specifically designed to enable you to group object operations into a single channel message, ensuring that the Ably system guarantees the atomicity of the applied changes.
+
+h2(#create). Create batch context
+
+blang[javascript].
+
+  To batch object operations together, use the @channel.objects.batch()@ method. This method accepts a callback function, which is provided with a batch context object. The batch context object provides a synchronous API to work with objects on a channel that stores operations inside the batch instead of applying them immediately.
+
+  Using the batch context ensures that operations are grouped and sent in a single channel message after the batch callback function has run. This guarantees that all changes are applied atomically by both the server and all clients.
+
+  <aside data-type='important'>
+  <p>
+    The batch callback function must be synchronous because the batch method sends the grouped operations as soon as the callback function completes. If you need to perform asynchronous operations (such as fetching data to do operations inside a batch), do so outside the callback function before calling @channel.objects.batch()@.
+  </p>
+  </aside>
+
+blang[javascript].
+
+  ```[javascript]
+  await channel.objects.batch((ctx) => {
+    const root = ctx.getRoot();
+
+    root.set('foo', 'bar');
+    root.set('baz', 42);
+
+    const counter = root.get('counter');
+    counter.increment(5);
+
+    // Batched operations are sent to the Ably system when the batch callback has run.
+  });
+  ```
+
+If an error occurs within the batch, all operations are discarded, preventing partial updates and ensuring atomicity.
+
+h3(#context). Batch context object
+
+blang[javascript].
+
+  The batch context provides a synchronous API for objects operations inside the batch callback. It mirrors the asynchronous API found on @channel.objects@, including "LiveCounter":/docs/liveobjects/counter and "LiveMap":/docs/liveobjects/map.
+
+  To access the batch API, call @BatchContext.getRoot()@, which synchronously returns a wrapper around the "root":/docs/liveobjects/concepts/objects#root-object object instance. This wrapper enables you to access and modify objects within a batch.
+
+  <aside data-type='note'>
+  <p>
+    Although the batch context provides a synchronous API, updates to objects are only applied _after_ the batch callback function has run and changes have been echoed back to the client, just like regular mutation operations.
+  </p>
+  </aside>
+
+blang[javascript].
+
+  ```[javascript]
+  await channel.objects.batch((ctx) => {
+    // Note: .getRoot() call on a batch context is synchronous.
+    // The returned root object is a special wrapper around a regular LiveMap instance,
+    // providing a synchronous mutation API.
+    const root = ctx.getRoot();
+
+    // Mutation operations like LiveMap.set and LiveCounter.increment
+    // are synchronous inside the batch and queue operations instead of applying them immediately.
+    root.set('foo', 'bar');
+    root.remove('baz');
+
+    // Access other objects through the root object from the BatchContext.getRoot() method.
+    const counter = root.get('counter');
+    counter.increment(5);
+  });
+  ```
+
+You cannot create new objects using the batch context. If you need to create new objects and add them to the channel as part of an atomic batch operation to guarantee atomicity, you must first create them using the regular @channel.objects@ API. Once the objects have been created, you can then assign them to the object tree inside a batch function.
+
+blang[javascript].
+
+  ```[javascript]
+  // First, create new objects outside the batch context
+  const counter = await channel.objects.createCounter();
+  const map = await channel.objects.createMap();
+
+  // Then, use a batch to assign them atomically to the channel objects
+  await channel.objects.batch((ctx) => {
+    const root = ctx.getRoot();
+    root.set('counter', counter);
+    root.set('map', map);
+  });
+  ```
+
+h3(#use-cases). When to batch operations
+
+Usually, you don't need to use batching for objects operations. It is only useful in situations where a group of operations must be applied together to maintain consistency in application state, or when there are multiple mutation operations that you might want to apply at the same time to improve the UI experience.
+
+For example, in a task dashboard application, you might want to remove all tasks on a board in a single operation to prevent excessive UI updates that the user would otherwise experience.
+
+blang[javascript].
+
+  ```[javascript]
+  await channel.objects.batch((ctx) => {
+    const root = ctx.getRoot();
+    const tasks = root.get('tasks');
+
+    for (const key of reactions.keys()) {
+      reactions.remove(key);
+    }
+  });
+  ```
+
+h3(#cancel). Cancel batch operation
+
+To explicitly cancel a batch before it is applied, throw an error inside the batch function. This prevents any queued operations from being applied.
+
+blang[javascript].
+
+  ```[javascript]
+  await channel.objects.batch((ctx) => {
+    const root = ctx.getRoot();
+    root.set('foo', 'bar');
+
+    // Throwing an error prevents any queued operations from being applied.
+    throw new Error('Cancel batch');
+  });
+  ```
+
+blang[javascript].
+
+  h3(#closed). Batch API cannot be used outside the callback function
+
+  The Batch API provided by the batch context object cannot be used outside the callback function. Attempting to do so results in an error. This applies both to @BatchContext.getRoot()@ and any object instances retrieved from it.
+
+blang[javascript].
+
+  ```[javascript]
+  let root;
+  await channel.objects.batch((ctx) => {
+    root = ctx.getRoot();
+  });
+
+  // Calling any Batch API methods outside the batch callback
+  // will throw an Error: Batch is closed.
+  root.set('foo', 'bar');
+  ```