Custom Plugin Client

This library runs inside a custom plugin iframe and talks to the host over window.postMessage. It supports JSON-RPC 2.0 (recommended) and a legacy envelope format (type on the message object) for older hosts.

Usage (JSON-RPC)

1. Import the client (default export is CustomPluginClient):

   import CustomPluginClient from "@oviceinc/custom-plugin-client";

2. Create an instance and call ready():

   const client = new CustomPluginClient();
   const disconnect = client.ready({ expectedOrigin: "https://example.com" });

3. Register event listeners with on:

   client.on("message", (payload) => {
     // Handle message event
   });
   
   client.on("participants", (payload) => {
     // Handle participants event
   });
   
   client.on("data_saved", (payload) => {
     // Host confirmed save
   });

4. Call void methods (JSON-RPC requests) or async RPC helpers:

   client.getParticipants();
   
   void client.getParticipantsAsync().then((list) => {
     console.log("RPC result", list);
   });
   
   client.sendMessage({
     to: "participantId",
     event: "eventName",
     message: "Hello, participant!",
   });
   
   client.broadcast({
     event: "eventName",
     message: "Hello, everyone!",
   });
   
   client.saveData({ key: "value" });

5. Remove listeners with off or Disposable.off() from on, or use addEventListeners for a batch:

   client.off("message", messageHandler);
   
   const removable = client.addEventListeners({
     message: messageHandler,
     participants: participantsHandler,
   });
   removable.removeEventListeners();

Replace https://example.com with the parent window origin you expect.

Legacy client (deprecated)

If the host only speaks legacy postMessage objects with a top-level type field (not JSON-RPC), use LegacyCustomPluginClient. It is deprecated; prefer migrating the host to JSON-RPC and using CustomPluginClient.

import { LegacyCustomPluginClient } from "@oviceinc/custom-plugin-client";

const client = new LegacyCustomPluginClient();
client.ready({ expectedOrigin: "https://example.com" });

On the legacy client, getParticipantsAsync, sendMessageAsync, broadcastAsync, and saveDataAsync throw—they require JSON-RPC. Only expectedOrigin from ready() options is used; rpcTimeoutMs is ignored.

JSON-RPC 2.0 (postMessage)

CustomPluginClient uses JSON-RPC 2.0 for outbound requests and inbound responses, and JSON-RPC notifications from the host (see table below).

ready() options (CustomPluginClient)

Option	Description
expectedOrigin	Strongly recommended: validates inbound MessageEvent.origin and sets the target origin for postMessage.
rpcTimeoutMs	Timeout in ms for JSON-RPC requests (default 30000).

Inbound notifications (host → iframe)

JSON-RPC method uses the same string as the legacy message type (e.g. ovice_participants).

method	Client event
ovice_participants	participants
ovice_message	message
ovice_participant_joined	joined
ovice_participant_left	left
ovice_participant_subscribed	subscribed
ovice_participant_unsubscribed	unsubscribed
ovice_shared_data	shared_data
ovice_data_saved_success	data_saved
ovice_errors	errors

Notifications must omit id (JSON-RPC notification). Batches are accepted as a JSON array of objects; each element is handled independently.

Outbound requests (iframe → host)

JSON-RPC method matches the legacy postMessage type for the same action.

method	params	Typical result
ovice_get_participants	{} (optional)	Participant[]
ovice_emit_message	Same shape as sendMessage / broadcast payloads	host-defined
ovice_save_and_emit_data	{ payload: object } (mirrors legacy save envelope)	host-defined

Errors use the standard JSON-RPC error object; async methods reject with JsonRpcError.

Async methods

getParticipantsAsync, sendMessageAsync, broadcastAsync, and saveDataAsync send JSON-RPC and return a Promise. They are only available on CustomPluginClient.

API

CustomPluginClient

JSON-RPC transport end-to-end. Default package export.

LegacyCustomPluginClient (deprecated)

Legacy type-only envelopes. Use CustomPluginClient for new work.

ready(options?): () => void

Initializes the client and returns a teardown function that removes the message listener and clears pending JSON-RPC state (on CustomPluginClient).

• CustomPluginClient: options — CustomPluginClientReadyOptions: optional expectedOrigin, rpcTimeoutMs.
• LegacyCustomPluginClient: same shape; only expectedOrigin is used.

on(event: SupportedMessage, callback: (payload: any) => void): Disposable

Registers a callback for the given event.

• event: participants, message, joined, left, subscribed, unsubscribed, shared_data, data_saved, or errors.
• callback: Handler invoked with the event payload.

getParticipants(): void

Requests the participant list (JSON-RPC on CustomPluginClient, legacy envelope on LegacyCustomPluginClient).

getParticipantsAsync(): Promise<Participant[]>

JSON-RPC request; resolves with the RPC result. Not supported on LegacyCustomPluginClient.

sendMessage(payload: CustomPluginSendMessagePayload): void

Sends a message to one participant (to, event, message).

sendMessageAsync(payload): Promise<unknown>

JSON-RPC variant of sendMessage.

broadcast(payload: CustomPluginBroadcastPayload): void

Broadcasts an event / message to all participants.

broadcastAsync(payload): Promise<unknown>

JSON-RPC variant of broadcast.

saveData(data: object): void

Saves data via the plugin host.

saveDataAsync(data: object): Promise<unknown>

JSON-RPC variant of saveData.

Migration notes

• CustomPluginClient is now JSON-RPC-only; there is no protocol / jsonRpcOutbound / "auto" switch on ready().
• If you relied on the previous default (legacy when protocol was omitted), use LegacyCustomPluginClient until the host supports JSON-RPC, then switch to CustomPluginClient.
• Legacy ovice_data_saved_success maps to the data_saved event (not message).

Exports

• Default: CustomPluginClient
• Named: LegacyCustomPluginClient, JsonRpcError, JsonRpcOutboundMethods, JsonRpcNotificationMethods, JsonRpcProtocol, and TypeScript types such as CustomPluginClientReadyOptions, LegacyCustomPluginClientReadyOptions, Participant, and payload types for host implementers.