@nnepoch/dtc-sdk 3.0.3 → 3.0.4

package/dist/cjs/index.d.cts

@@ -2558,6 +2558,20 @@ interface StreamRequestPromise<TResult> extends Promise<ApiResponseEnvelope<TRes
   readonly requestId: string;
   cancel: (reason?: string) => void;
 }
+/**
+ * 发送失败（UE 交互通道/视频未就绪）时的排队重试配置。
+ */
+interface RequestSendRetryOptions {
+  /**
+   * 是否在发送失败时排队重试（底层 Pixel Streaming 在视频 `readyState` 为 0 时会拒绝发送）。
+   * 默认 `true`。
+   */
+  enabled?: boolean;
+  /** 重试间隔（毫秒），默认 250。 */
+  intervalMs?: number;
+  /** 排队重试的最大等待时长（毫秒），超时仍未发出则 reject，默认 15000。 */
+  maxWaitMs?: number;
+}
 /**
  * RequestBridge 的 QoS 生命周期钩子。
  */
@@ -2586,6 +2600,14 @@ declare class RequestBridge {
    * 等待 UE 响应的进行中请求集合。
    */
   private pending;
+  /**
+   * 因 UE 交互通道未就绪而排队等待重发的请求集合。
+   */
+  private sendRetries;
+  /**
+   * 发送失败排队重试配置。
+   */
+  private readonly retryOptions;
   /**
    * SDK 运行时固定使用的响应事件通道名。
    */
@@ -2605,7 +2627,7 @@ declare class RequestBridge {
   /**
    * 初始化时立即注册响应监听，确保所有 API 调用共享同一桥接器。
    */
-  constructor(session: PixelStreamingAdapter, logger?: ModuleLogger, hooks?: RequestBridgeHooks);
+  constructor(session: PixelStreamingAdapter, logger?: ModuleLogger, hooks?: RequestBridgeHooks, retryOptions?: RequestSendRetryOptions);
   /**
    * 向 UE 发送请求信封，并在匹配响应到达后完成 Promise。
    */
@@ -2616,6 +2638,17 @@ declare class RequestBridge {
    */
   sendStreamRequest<TPayload, TResult>(module: string, method: string, payload?: TPayload, callback?: StreamRequestCallback<TResult>): StreamRequestPromise<TResult>;
   private sendPendingRequest;
+  /**
+   * 处理一次发送尝试：底层通道未就绪导致失败时按配置排队重试，
+   * 避免视频尚未就绪（`readyState === 0`）瞬间的请求被直接丢弃。
+   */
+  private handleSendAttempt;
+  private scheduleSendRetry;
+  private runSendRetry;
+  /**
+   * 清理指定请求的排队重试状态（取消定时器）。
+   */
+  private clearSendRetry;
   private settlePendingFailure;
   private handleResponse;
   private createRequestEnvelope;
@@ -4154,7 +4187,7 @@ declare class Navigation extends BaseApi {
      * @agentSideEffects write
      * @agentPreconditions DTCEngine 已完成鉴权并建立 WebRTC 连接
      * @agentRiskLevel low
-     * @agentExample { parentId: 'Players', id: 'Player1' nodes: [{ x: 114.7985155712282, y: 34.842421780635625, z: 2 }, { x: 114.79789723105696, y: 34.84218433379876, z: 1.5 }], isCache: false, planColor: '#00ff00', passColor: '#e1e1e1' }
+     * @agentExample { parentId: 'Players', id: 'Player1', nodes: [{ x: 114.7985155712282, y: 34.842421780635625, z: 2 }, { x: 114.79789723105696, y: 34.84218433379876, z: 1.5 }], isCache: false, planColor: '#00ff00', passColor: '#e1e1e1' }
      * @example
      * ```ts
       dtcEngine.Navigation.startNav({

package/dist/esm/index.d.ts

@@ -2558,6 +2558,20 @@ interface StreamRequestPromise<TResult> extends Promise<ApiResponseEnvelope<TRes
   readonly requestId: string;
   cancel: (reason?: string) => void;
 }
+/**
+ * 发送失败（UE 交互通道/视频未就绪）时的排队重试配置。
+ */
+interface RequestSendRetryOptions {
+  /**
+   * 是否在发送失败时排队重试（底层 Pixel Streaming 在视频 `readyState` 为 0 时会拒绝发送）。
+   * 默认 `true`。
+   */
+  enabled?: boolean;
+  /** 重试间隔（毫秒），默认 250。 */
+  intervalMs?: number;
+  /** 排队重试的最大等待时长（毫秒），超时仍未发出则 reject，默认 15000。 */
+  maxWaitMs?: number;
+}
 /**
  * RequestBridge 的 QoS 生命周期钩子。
  */
@@ -2586,6 +2600,14 @@ declare class RequestBridge {
    * 等待 UE 响应的进行中请求集合。
    */
   private pending;
+  /**
+   * 因 UE 交互通道未就绪而排队等待重发的请求集合。
+   */
+  private sendRetries;
+  /**
+   * 发送失败排队重试配置。
+   */
+  private readonly retryOptions;
   /**
    * SDK 运行时固定使用的响应事件通道名。
    */
@@ -2605,7 +2627,7 @@ declare class RequestBridge {
   /**
    * 初始化时立即注册响应监听，确保所有 API 调用共享同一桥接器。
    */
-  constructor(session: PixelStreamingAdapter, logger?: ModuleLogger, hooks?: RequestBridgeHooks);
+  constructor(session: PixelStreamingAdapter, logger?: ModuleLogger, hooks?: RequestBridgeHooks, retryOptions?: RequestSendRetryOptions);
   /**
    * 向 UE 发送请求信封，并在匹配响应到达后完成 Promise。
    */
@@ -2616,6 +2638,17 @@ declare class RequestBridge {
    */
   sendStreamRequest<TPayload, TResult>(module: string, method: string, payload?: TPayload, callback?: StreamRequestCallback<TResult>): StreamRequestPromise<TResult>;
   private sendPendingRequest;
+  /**
+   * 处理一次发送尝试：底层通道未就绪导致失败时按配置排队重试，
+   * 避免视频尚未就绪（`readyState === 0`）瞬间的请求被直接丢弃。
+   */
+  private handleSendAttempt;
+  private scheduleSendRetry;
+  private runSendRetry;
+  /**
+   * 清理指定请求的排队重试状态（取消定时器）。
+   */
+  private clearSendRetry;
   private settlePendingFailure;
   private handleResponse;
   private createRequestEnvelope;
@@ -4154,7 +4187,7 @@ declare class Navigation extends BaseApi {
      * @agentSideEffects write
      * @agentPreconditions DTCEngine 已完成鉴权并建立 WebRTC 连接
      * @agentRiskLevel low
-     * @agentExample { parentId: 'Players', id: 'Player1' nodes: [{ x: 114.7985155712282, y: 34.842421780635625, z: 2 }, { x: 114.79789723105696, y: 34.84218433379876, z: 1.5 }], isCache: false, planColor: '#00ff00', passColor: '#e1e1e1' }
+     * @agentExample { parentId: 'Players', id: 'Player1', nodes: [{ x: 114.7985155712282, y: 34.842421780635625, z: 2 }, { x: 114.79789723105696, y: 34.84218433379876, z: 1.5 }], isCache: false, planColor: '#00ff00', passColor: '#e1e1e1' }
      * @example
      * ```ts
       dtcEngine.Navigation.startNav({