Implement LiveObjects REST client

Adds REST support for Objects REST API endpoints:
- GET /channels/{channel}/object/{id?}?compact={boolean}&path={string}
- POST /channels/{channel}/object

Resolves PUB-1197

Author: VeskeR

liveobjects.d.ts

@@ -12,11 +12,12 @@ import {
   EventCallback,
   RealtimeChannel,
   RealtimeClient,
+  RestClient,
   StatusSubscription,
   Subscription,
   __livetype,
 } from './ably';
-import { BaseRealtime } from './modular';
+import { BaseRealtime, BaseRest, Rest } from './modular';
 /* eslint-enable no-unused-vars, @typescript-eslint/no-unused-vars */
 
 /**
@@ -67,7 +68,256 @@ export type ObjectsEventCallback = () => void;
 export type BatchFunction<T extends LiveObject> = (ctx: BatchContext<T>) => void;
 
 /**
- * Enables the Objects to be read, modified and subscribed to for a channel.
+ * Enables REST-based operations on Objects on a channel.
+ */
+export declare interface RestObject {
+  /**
+   * Reads object data from the channel in a compact format.
+   * Uses the channel's root object as the entrypoint when no objectId is provided.
+   *
+   * @param params - Optional parameters to specify the object to fetch and the format of the returned data.
+   * @returns A promise that resolves to the object data in compact format, or `undefined` if the specified objectId/path does not resolve to an object.
+   */
+  get(params?: Omit<GetObjectParams, 'compact'> & { compact?: true }): Promise<RestCompactObjectData | undefined>;
+  /**
+   * Reads object data from the channel in expanded format.
+   * Uses the channel's root object as the entrypoint when no objectId is provided.
+   *
+   * @param params - Parameters specifying the object to fetch with `compact: false`.
+   * @returns A promise that resolves to the object data in expanded format, or `undefined` if the specified objectId/path does not resolve to an object.
+   */
+  get(params: Omit<GetObjectParams, 'compact'> & { compact: false }): Promise<RestLiveObject | undefined>;
+  /**
+   * Reads object data from the channel.
+   * Uses the channel's root object as the entrypoint when no objectId is provided.
+   *
+   * @param params - Optional parameters to specify the object to fetch and the format of the returned data.
+   * @returns A promise that resolves to the object data in the requested format, or `undefined` if the specified objectId/path does not resolve to an object.
+   */
+  get(params?: GetObjectParams): Promise<RestCompactObjectData | RestLiveObject | undefined>;
+
+  /**
+   * Publishes one or more operations to modify objects on the channel.
+   *
+   * @param op - A single operation or array of operations to publish.
+   * @returns A promise that resolves to a {@link RestObjectPublishResult} containing information about the published operations.
+   */
+  publish(op: RestObjectOperation | RestObjectOperation[]): Promise<RestObjectPublishResult>;
+}
+
+/**
+ * Base interface for all REST object operations. Contains common fields shared across all operation types.
+ */
+export interface RestObjectOperationBase {
+  /**
+   * An ID associated with the message. Clients may set this field explicitly when publishing an operation to enable
+   * idempotent publishing. If not set, this will be generated by the server.
+   */
+  id?: string;
+  /**
+   * A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include `headers`.
+   */
+  extras?: {
+    /**
+     * A set of key–value pair headers included with this object message.
+     */
+    headers?: Record<string, string>;
+    [key: string]: any;
+  };
+}
+
+// Enforce exactly one target at compile time using a union of the types below.
+/**
+ * Targets an object by its object ID.
+ */
+type TargetByObjectId = { objectId: string; path?: never };
+
+/**
+ * Targets an object by its location using the path.
+ * Paths are expressed relative to the structure of the object as defined by the compact view of the object tree.
+ */
+type TargetByPath = { path: string; objectId?: never };
+
+/**
+ * Base type for operations that can target objects either by object ID or by path.
+ * Ensures that exactly one targeting method is specified.
+ */
+export type AnyTargetOperationBase = RestObjectOperationBase & (TargetByObjectId | TargetByPath);
+
+/**
+ * Operation to create a new map object at the specified path with initial entries.
+ */
+export type OperationMapCreate = RestObjectOperationBase &
+  TargetByPath & {
+    operation: ObjectOperationActions.MAP_CREATE;
+    entries: Record<string, PrimitiveOrObjectReference>;
+  };
+
+/**
+ * Operation to set a key to a specified value in an existing map object.
+ * Can target the map by either object ID or path.
+ */
+export type OperationMapSet = AnyTargetOperationBase & {
+  operation: ObjectOperationActions.MAP_SET;
+  key: string;
+  value: PrimitiveOrObjectReference;
+  encoding?: string;
+};
+
+/**
+ * Operation to remove a key from an existing map object.
+ * Can target the map by either object ID or path.
+ */
+export type OperationMapRemove = AnyTargetOperationBase & {
+  operation: ObjectOperationActions.MAP_REMOVE;
+  key: string;
+};
+
+/**
+ * Operation to create a new counter object at the specified path with an initial count value.
+ */
+export type OperationCounterCreate = RestObjectOperationBase &
+  TargetByPath & {
+    operation: ObjectOperationActions.COUNTER_CREATE;
+    count: number;
+  };
+
+/**
+ * Operation to increment (or decrement with negative values) an existing counter object.
+ * Can target the counter by either object ID or path.
+ */
+export type OperationCounterInc = AnyTargetOperationBase & {
+  operation: ObjectOperationActions.COUNTER_INC;
+  amount: number;
+};
+
+/**
+ * Union type representing all possible REST object operations.
+ */
+export type RestObjectOperation =
+  | OperationMapCreate
+  | OperationMapSet
+  | OperationMapRemove
+  | OperationCounterCreate
+  | OperationCounterInc;
+
+/**
+ * Result returned after successfully publishing object operations via REST.
+ * Contains information about the published message and affected object IDs.
+ */
+export interface RestObjectPublishResult {
+  /** The ID of the message containing the published operations. */
+  messageId: string;
+  /** The name of the channel the object message was published to. */
+  channel: string;
+  /**
+   * Array of object IDs that were affected by the operations.
+   * May include multiple IDs for wildcard paths and batch operations.
+   */
+  objectIds: string[];
+}
+
+/**
+ * Compact representation of object data returned from {@link RestObject.get} when `compact=true` (default).
+ * Provides a JSON-like view with primitive values, nested objects, and object references for handling cycles.
+ */
+export type RestCompactObjectData =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonArray
+  | JsonObject
+  | { objectId: string } // cyclic references handling
+  | { [key: string]: RestCompactObjectData };
+
+/**
+ * Object representation returned from {@link RestObject.get} when `compact=false`.
+ * Provides an expanded structural view with object metadata.
+ */
+export type RestLiveObject = RestLiveMap | RestLiveCounter | AnyRestLiveObject;
+
+/**
+ * Expanded representation of a map object with metadata.
+ */
+export interface RestLiveMap {
+  /** The ID of the map object. */
+  objectId: string;
+  /** Describes the value of a map object. */
+  map: {
+    /** The conflict-resolution semantics used by the map object, one of the {@link ObjectsMapSemantics} enum values. */
+    semantics: ObjectsMapSemantics;
+    /** The map entries, indexed by key. */
+    entries: Record<string, RestObjectMapEntry>;
+  };
+}
+
+/**
+ * Describes a value at a specific key in a map object.
+ */
+export interface RestObjectMapEntry {
+  /** The value associated with this map entry. */
+  data: RestLiveObject | RestObjectData;
+}
+
+/**
+ * Represents a value in an object on a channel.
+ * Either a primitive data or a reference to another object.
+ */
+export interface RestObjectData {
+  /** Reference to another object by its ID. */
+  objectId?: string;
+  /** A numeric value. */
+  number?: number;
+  /** A boolean value. */
+  boolean?: boolean;
+  /** A string value. */
+  string?: string;
+  /** A binary value. Typed differently depending on platform (`Buffer` in Node.js, `ArrayBuffer` elsewhere). */
+  bytes?: Buffer | ArrayBuffer;
+  /** A JSON value (array or object). */
+  json?: JsonArray | JsonObject;
+}
+
+/**
+ * Expanded representation of a counter object with metadata.
+ */
+export interface RestLiveCounter {
+  /** The ID of the counter object. */
+  objectId: string;
+  /** Describes the value of a counter object. */
+  counter: {
+    /** Holds the value of the counter. */
+    data: {
+      /** The value of the counter. */
+      number: number;
+    };
+  };
+}
+
+/**
+ * Fallback type for compatibility with future object types.
+ */
+export type AnyRestLiveObject = {
+  /** The ID of the object, available for all object types. */
+  objectId: string;
+};
+
+/**
+ * Request parameters for {@link RestObject.get}.
+ * All parameters are optional since the default behavior is to fetch the channel's root object with `compact=true`.
+ */
+export interface GetObjectParams {
+  /** The object ID to fetch. If omitted, the entrypoint is the channel's root object. */
+  objectId?: string;
+  /** Path evaluated relative to the entrypoint (root or specified objectId). */
+  path?: string;
+  /** Whether to return compact representation. Defaults to true. */
+  compact?: boolean;
+}
+
+/**
+ * Enables the Objects to be read, modified and subscribed to for a realtime channel.
  */
 export declare interface RealtimeObject {
   /**
@@ -124,6 +374,14 @@ export type Primitive =
   | JsonArray
   | JsonObject;
 
+/**
+ * Primitive types and object references that may appear in `data` fields
+ * of response bodies when using the Objects REST API.
+ *
+ * References to other objects are represented as `{ objectId: string }`.
+ */
+export type PrimitiveOrObjectReference = Primitive | { objectId: string };
+
 /**
  * Represents a JSON-encodable value.
  */
@@ -1492,7 +1750,7 @@ declare namespace ObjectOperationActions {
 }
 
 /**
- * The possible values of the `action` field of an {@link ObjectOperation}.
+ * Describes object operation types for {@link ObjectOperation} and {@link RestObjectOperation}.
  */
 export type ObjectOperationAction =
   | ObjectOperationActions.MAP_CREATE
@@ -1793,22 +2051,23 @@ export class LiveCounter {
 }
 
 /**
- * The LiveObjects plugin that provides a {@link RealtimeClient} instance with the ability to use LiveObjects functionality.
+ * The LiveObjects plugin that provides a {@link RestClient} or {@link RealtimeClient} instance with the ability to use LiveObjects functionality.
  *
- * To create a client that includes this plugin, include it in the client options that you pass to the {@link RealtimeClient.constructor}:
+ * To create a client that includes this plugin, include it in the client options that you pass to the {@link RestClient.constructor} or {@link RealtimeClient.constructor}:
  *
  * ```javascript
  * import { Realtime } from 'ably';
  * import { LiveObjects } from 'ably/liveobjects';
  * const realtime = new Realtime({ ...options, plugins: { LiveObjects } });
  * ```
  *
- * The LiveObjects plugin can also be used with a {@link BaseRealtime} client:
+ * The LiveObjects plugin can also be used with a {@link BaseRest} or {@link BaseRealtime} client,
+ * with the additional requirement that you must also use the {@link Rest} plugin
  *
  * ```javascript
- * import { BaseRealtime, WebSocketTransport, FetchRequest } from 'ably/modular';
+ * import { BaseRealtime, Rest, WebSocketTransport, FetchRequest } from 'ably/modular';
  * import { LiveObjects } from 'ably/liveobjects';
- * const realtime = new BaseRealtime({ ...options, plugins: { WebSocketTransport, FetchRequest, LiveObjects } });
+ * const realtime = new BaseRealtime({ ...options, plugins: { Rest, WebSocketTransport, FetchRequest, LiveObjects } });
  * ```
  *
  * You can also import individual utilities alongside the plugin:
@@ -1832,3 +2091,17 @@ declare module 'ably' {
     object: RealtimeObject;
   }
 }
+
+/**
+ * Module augmentation to add the `object` property to `RestChannel` when
+ * importing from 'ably/liveobjects'. This ensures all LiveObjects types come from
+ * the same module (CJS or ESM), avoiding type incompatibility issues.
+ */
+declare module 'ably' {
+  interface RestChannel {
+    /**
+     * A {@link RestObject} object.
+     */
+    object: RestObject;
+  }
+}

scripts/moduleReport.ts

@@ -341,6 +341,7 @@ async function checkLiveObjectsPluginFiles() {
     'src/plugins/liveobjects/pathobject.ts',
     'src/plugins/liveobjects/pathobjectsubscriptionregister.ts',
     'src/plugins/liveobjects/realtimeobject.ts',
+    'src/plugins/liveobjects/restobject.ts',
     'src/plugins/liveobjects/rootbatchcontext.ts',
     'src/plugins/liveobjects/syncobjectspool.ts',
   ]);

src/common/lib/client/baseclient.ts

@@ -20,6 +20,7 @@ import { FilteredSubscriptions } from './filteredsubscriptions';
 import type { LocalDevice } from 'plugins/push/pushactivation';
 import EventEmitter from '../util/eventemitter';
 import { MessageEncoding } from '../types/basemessage';
+import type * as LiveObjectsPlugin from 'plugins/liveobjects';
 
 type BatchResult<T> = API.BatchResult<T>;
 type BatchPublishSpec = API.BatchPublishSpec;
@@ -50,6 +51,7 @@ class BaseClient {
   readonly _additionalHTTPRequestImplementations: HTTPRequestImplementations | null;
   private readonly __FilteredSubscriptions: typeof FilteredSubscriptions | null;
   readonly _Annotations: AnnotationsPlugin | null;
+  readonly _liveObjectsPlugin: typeof LiveObjectsPlugin | null;
   readonly logger: Logger;
   _device?: LocalDevice;
 
@@ -103,6 +105,7 @@ class BaseClient {
     this._Crypto = options.plugins?.Crypto ?? null;
     this.__FilteredSubscriptions = options.plugins?.MessageInteractions ?? null;
     this._Annotations = options.plugins?.Annotations ?? null;
+    this._liveObjectsPlugin = options.plugins?.LiveObjects ?? null;
   }
 
   get rest(): Rest {

src/common/lib/client/baserealtime.ts

@@ -13,14 +13,12 @@ import { ModularPlugins, RealtimePresencePlugin } from './modularplugins';
 import { TransportNames } from 'common/constants/TransportName';
 import { TransportImplementations } from 'common/platform';
 import Defaults from '../util/defaults';
-import type * as LiveObjectsPlugin from 'plugins/liveobjects';
 
 /**
  `BaseRealtime` is an export of the tree-shakable version of the SDK, and acts as the base class for the `DefaultRealtime` class exported by the non tree-shakable version.
  */
 class BaseRealtime extends BaseClient {
   readonly _RealtimePresence: RealtimePresencePlugin | null;
-  readonly _liveObjectsPlugin: typeof LiveObjectsPlugin | null;
   // Extra transport implementations available to this client, in addition to those in Platform.Transports.bundledImplementations
   readonly _additionalTransportImplementations: TransportImplementations;
   _channels: any;
@@ -60,7 +58,6 @@ class BaseRealtime extends BaseClient {
 
     this._additionalTransportImplementations = BaseRealtime.transportImplementationsFromPlugins(this.options.plugins);
     this._RealtimePresence = this.options.plugins?.RealtimePresence ?? null;
-    this._liveObjectsPlugin = this.options.plugins?.LiveObjects ?? null;
     this.connection = new Connection(this, this.options);
     this._channels = new Channels(this);
     if (this.options.autoConnect !== false) this.connect();