@yorkie-js/sdk 0.7.8 → 0.7.10-rc

package/dist/yorkie-js-sdk.d.ts

@@ -106,9 +106,10 @@ export declare interface AttachChannelOptions {
      */
     syncMode?: SyncMode;
     /**
-     * `channelHeartbeatInterval` overrides the heartbeat interval (ms) for this
-     * attachment. If unset, mode-specific defaults apply: Polling=3000,
-     * Realtime=30000.
+     * `channelHeartbeatInterval` overrides the heartbeat interval (ms) for
+     * this attachment. If unset, the client-level default
+     * (`ClientOptions.channelHeartbeatInterval`, default 5000 ms) applies
+     * to both Realtime and Polling modes.
      */
     channelHeartbeatInterval?: number;
 }
@@ -801,6 +802,12 @@ export declare class Channel implements Observable_2<ChannelEvent>, Attachable {
      * The callback will be called when an authentication error occurs.
      */
     subscribe(type: 'auth-error', next: ChannelEventCallbackMap['auth-error']): Unsubscribe;
+    /**
+     * `subscribe` registers a callback to subscribe to non-recoverable sync
+     * (RefreshChannel) errors. Subsequent successful events on the channel
+     * imply recovery — there is no separate "recovered" event.
+     */
+    subscribe(type: 'sync-error', next: ChannelEventCallbackMap['sync-error']): Unsubscribe;
     /**
      * `subscribe` registers a callback to subscribe to presence events on the channel.
      * The callback will be called when the presence count changes.
@@ -834,7 +841,7 @@ export declare class Channel implements Observable_2<ChannelEvent>, Attachable {
 /**
  * `ChannelEvent` represents an event that occurs in the channel.
  */
-export declare type ChannelEvent = PresenceEvent_3 | BroadcastEvent | LocalBroadcastEvent | AuthErrorEvent_3;
+export declare type ChannelEvent = PresenceEvent_3 | BroadcastEvent | LocalBroadcastEvent | AuthErrorEvent_3 | SyncErrorEvent;
 
 /**
  * `ChannelEventCallbackMap` represents a map of event types to callbacks.
@@ -843,6 +850,7 @@ declare type ChannelEventCallbackMap = {
     broadcast: NextFn<BroadcastEvent>;
     'local-broadcast': NextFn<LocalBroadcastEvent>;
     'auth-error': NextFn<AuthErrorEvent_3>;
+    'sync-error': NextFn<SyncErrorEvent>;
     presence: NextFn<PresenceEvent_3>;
     all: NextFn<ChannelEvent>;
 };
@@ -870,7 +878,15 @@ export declare enum ChannelEventType {
     /**
      * `AuthError` means that an authentication error has occurred.
      */
-    AuthError = "auth-error"
+    AuthError = "auth-error",
+    /**
+     * `SyncError` means that a non-recoverable sync (RefreshChannel) error
+     * occurred. Subscribers can use this to render an error state in the UI
+     * without polling internal SDK state. The SDK still retries via its sync
+     * loop, so subsequent successful events (PresenceChanged/Initialized) can
+     * be treated as recovery.
+     */
+    SyncError = "sync-error"
 }
 
 /**
@@ -1010,8 +1026,9 @@ export declare class Client {
      */
     attach<R, P extends Indexable>(resource: Document_2<R, P>, opts?: AttachOptions<R, P>): Promise<Document_2<R, P>>;
     /**
-     * `attach` attaches the given channel to this client. It tells the server that
-     * this client will track the channel.
+     * `attach` attaches the given channel to this client. The channel is
+     * registered locally and the server is notified on the next RefreshChannel
+     * heartbeat.
      */
     attach(resource: Channel, opts?: AttachChannelOptions): Promise<Channel>;
     /**
@@ -1027,8 +1044,9 @@ export declare class Client {
         keepalive?: boolean;
     }): Promise<Document_2<R, P>>;
     /**
-     * `detach` detaches the given channel from this client.
-     * It tells the server that this client will no longer track the channel.
+     * `detach` detaches the given channel from this client. The detach is a
+     * local cleanup; the server reclaims the session via TTL when heartbeats
+     * stop.
      */
     detach(resource: Channel): Promise<Channel>;
     /**
@@ -1041,13 +1059,15 @@ export declare class Client {
      */
     private detachDocument;
     /**
-     * `attach` attaches the given channel to this client.
-     * It tells the server that this client will track the channel.
+     * `attachChannel` attaches the given channel to this client. The channel is
+     * registered locally and the server is notified on the next RefreshChannel
+     * heartbeat.
      */
     attachChannel(channel: Channel, opts?: AttachChannelOptions): Promise<Channel>;
     /**
-     * `detachChannel` detaches the given channel from this client.
-     * It tells the server that this client will no longer track the channel.
+     * `detachChannel` detaches the given channel from this client. The detach
+     * is a local cleanup; the server reclaims the session via TTL when
+     * heartbeats stop.
      */
     detachChannel(channel: Channel): Promise<Channel>;
     /**
@@ -1122,6 +1142,17 @@ export declare class Client {
      * `restoreRevision` restores the document to the given revision.
      */
     restoreRevision<R, P extends Indexable>(doc: Document_2<R, P>, revisionId: string): Promise<void>;
+    /**
+     * `peekChannel` reads the current session count of a channel without
+     * creating a session on the server. Use this when the caller only needs
+     * to display the count (e.g. "N people writing") without contributing to
+     * it and without receiving broadcasts.
+     *
+     * Unlike `attach({ readOnly: true })`, this does not occupy a `Session`
+     * entry on the server, does not generate heartbeat RPCs, and does not
+     * subscribe to channel events. Polling is the caller's responsibility.
+     */
+    peekChannel(channelKey: string): Promise<number>;
     /**
      * `broadcast` broadcasts the given payload to the given topic.
      */
@@ -1230,9 +1261,11 @@ export declare interface ClientOptions {
      */
     reconnectStreamDelay?: number;
     /**
-     * `channelHeartbeatInterval` is the interval of the channel heartbeat.
-     * The client sends a heartbeat to the server to refresh the channel TTL.
-     * The default value is `30000`(ms).
+     * `channelHeartbeatInterval` is the interval of the channel heartbeat (ms).
+     * The client sends a `RefreshChannel` heartbeat to refresh the channel
+     * session TTL. The default value is `5000` (ms) — co-tuned to the server's
+     * `ChannelSessionTTL` (15 s) at TTL/3. Values larger than the server TTL
+     * risk premature session expiry.
      */
     channelHeartbeatInterval?: number;
     /**
@@ -6051,6 +6084,26 @@ declare interface SubscribeFn<T> {
     (observer: Observer<T>): Unsubscribe;
 }
 
+/**
+ * `SyncErrorEvent` represents a non-recoverable sync (RefreshChannel) error.
+ * It carries the underlying error object so subscribers can inspect codes
+ * (e.g. via `isErrorCode`) without losing the original Error.
+ */
+declare interface SyncErrorEvent {
+    /**
+     * `type` is the type of the event.
+     */
+    type: ChannelEventType.SyncError;
+    /**
+     * `error` is the underlying error thrown by the RPC call.
+     */
+    error: unknown;
+    /**
+     * `method` is the RPC method that failed (e.g. `RefreshChannel`).
+     */
+    method: string;
+}
+
 /**
  * `SyncMode` defines synchronization modes for the PushPullChanges API
  * (documents) and the RefreshChannel heartbeat (channels).