@comfyorg/comfyui-desktop-bridge-types 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Comfy Org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @comfyorg/comfyui-desktop-bridge-types
+
+TypeScript definitions for `window.__comfyDesktop2`, the API Comfy Desktop
+exposes to the frontend it hosts.
+
+```sh
+npm install --save-dev @comfyorg/comfyui-desktop-bridge-types
+```
+
+```ts
+import type { ComfyDesktop2Bridge } from '@comfyorg/comfyui-desktop-bridge-types'
+
+declare global {
+  interface Window {
+    __comfyDesktop2?: ComfyDesktop2Bridge
+  }
+}
+```
+
+## Every member is optional for a reason
+
+Which members actually exist at runtime is decided by the Desktop binary the
+user is running, and Desktop binaries update far more slowly than the frontend
+that ships into them. Callers must guard every access and carry a fallback —
+including when the member exists but rejects:
+
+```ts
+async function openModelAccessPage(url: string): Promise<void> {
+  try {
+    if ((await window.__comfyDesktop2?.openModelAccessPage?.(url)) === true) return
+  } catch (error) {
+    console.error('Desktop could not open the access page:', error)
+  }
+  window.open(url, '_blank', 'noopener,noreferrer')
+}
+```
+
+`ComfyDesktop2BridgeImplementation` is the provider-side counterpart: it makes
+every top-level member required, so Desktop's preload cannot claim the contract
+while omitting part of it.
+
+## Provenance
+
+Generated from `src/types/comfyDesktopBridge.ts` in
+[Comfy-Org/Comfy-Desktop](https://github.com/Comfy-Org/Comfy-Desktop), which is
+the same file the preload implements. Edit that file, run
+`pnpm run bridge-types:gen`, and bump the version in this package's
+`package.json`. Merging to `main` then publishes it; CI refuses a contract
+change that arrives without a bump.

package/comfyDesktopBridge.d.ts

@@ -1,66 +1,100 @@
 export interface ComfyDownloadProgress {
-    url: string;
-    filename: string;
-    directory?: string;
-    progress: number;
-    receivedBytes?: number;
-    totalBytes?: number;
-    speedBytesPerSec?: number;
-    etaSeconds?: number;
-    status: 'pending' | 'downloading' | 'paused' | 'completed' | 'error' | 'cancelled';
-    error?: string;
-    isImage?: boolean;
+  /** Stable per-job identifier assigned by the desktop app. The download
+   *  controls accept it in place of the URL. Optional: older desktop
+   *  versions do not send it. */
+  id?: string
+  url: string
+  filename: string
+  directory?: string
+  progress: number
+  receivedBytes?: number
+  totalBytes?: number
+  speedBytesPerSec?: number
+  etaSeconds?: number
+  status: 'pending' | 'downloading' | 'paused' | 'completed' | 'error' | 'cancelled'
+  error?: string
+  isImage?: boolean
 }
 export interface TerminalRestore {
-    buffer: string[];
-    size: {
-        cols: number;
-        rows: number;
-    };
-    exited: boolean;
+  buffer: string[]
+  size: {
+    cols: number
+    rows: number
+  }
+  exited: boolean
 }
 export interface LogsRestore {
-    installationId: string;
-    buffer: string[];
+  installationId: string
+  buffer: string[]
 }
 export interface LogsOutputMsg {
-    installationId: string;
-    text: string;
+  installationId: string
+  text: string
 }
-export type ComfyDesktop2TelemetryValue = string | number | boolean | null;
-export type ComfyDesktop2TelemetryProperties = Record<string, ComfyDesktop2TelemetryValue | ComfyDesktop2TelemetryValue[]>;
+export type ComfyDesktop2TelemetryValue = string | number | boolean | null
+export type ComfyDesktop2TelemetryProperties = Record<
+  string,
+  ComfyDesktop2TelemetryValue | ComfyDesktop2TelemetryValue[]
+>
+export type ComfyDesktop2FirebaseAuthState =
+  | {
+      status: 'pending'
+    }
+  | {
+      status: 'signed_out'
+    }
+  | {
+      status: 'signed_in'
+      userId: string
+    }
 export interface ComfyDesktop2TerminalBridge {
-    subscribe(installationId?: string): Promise<TerminalRestore>;
-    unsubscribe(installationId?: string): Promise<void>;
-    write(data: string, installationId?: string): Promise<void>;
-    resize(cols: number, rows: number, installationId?: string): Promise<void>;
-    restart(installationId?: string): Promise<TerminalRestore>;
-    openPopout(): Promise<void>;
-    onOutput(callback: (data: string) => void): () => void;
-    onExited(callback: () => void): () => void;
+  subscribe(installationId?: string): Promise<TerminalRestore>
+  unsubscribe(installationId?: string): Promise<void>
+  write(data: string, installationId?: string): Promise<void>
+  resize(cols: number, rows: number, installationId?: string): Promise<void>
+  restart(installationId?: string): Promise<TerminalRestore>
+  openPopout(): Promise<void>
+  onOutput(callback: (data: string) => void): () => void
+  onExited(callback: () => void): () => void
 }
 export interface ComfyDesktop2LogsBridge {
-    subscribe(installationId?: string): Promise<LogsRestore>;
-    unsubscribe(installationId?: string): Promise<void>;
-    openPopout(): Promise<void>;
-    onOutput(callback: (msg: LogsOutputMsg) => void): () => void;
+  subscribe(installationId?: string): Promise<LogsRestore>
+  unsubscribe(installationId?: string): Promise<void>
+  openPopout(): Promise<void>
+  onOutput(callback: (msg: LogsOutputMsg) => void): () => void
 }
 export interface ComfyDesktop2TelemetryBridge {
-    capture(event: string, properties?: ComfyDesktop2TelemetryProperties): void;
+  capture(event: string, properties?: ComfyDesktop2TelemetryProperties): void
+  /** Report the hosted view's complete Firebase state for process-wide consensus. */
+  reportFirebaseAuthState?(state: ComfyDesktop2FirebaseAuthState): void
 }
 export interface ComfyDesktop2Bridge {
-    isRemote(): boolean;
-    downloadModel?: (url: string, filename: string, directory: string) => Promise<boolean>;
-    downloadAsset?: (url: string, filename: string, authToken?: string) => Promise<boolean>;
-    pauseDownload?: (url: string) => Promise<boolean>;
-    resumeDownload?: (url: string) => Promise<boolean>;
-    cancelDownload?: (url: string) => Promise<boolean>;
-    onDownloadProgress?: (callback: (data: ComfyDownloadProgress) => void) => () => void;
-    reportTheme?: (bg: string, text: string) => void;
-    Terminal?: ComfyDesktop2TerminalBridge;
-    Logs?: ComfyDesktop2LogsBridge;
-    Telemetry?: ComfyDesktop2TelemetryBridge;
+  /** Reports whether the backend server is cloud/remote, not the user's location.
+   *  Optional: desktop builds predating it are still in the wild. */
+  isRemote?(): boolean
+  openTerminal?: () => Promise<boolean>
+  openMcpSetup?: () => Promise<boolean>
+  /** Opens a model provider access page in the hosted frontend's browser session.
+   *  Resolves `true` when the host has taken ownership of the request.
+   *  On `false` or rejection the frontend falls back to opening a new tab. */
+  openModelAccessPage?: (url: string) => Promise<boolean>
+  downloadModel?: (url: string, filename: string, directory: string) => Promise<boolean>
+  downloadAsset?: (url: string, filename: string, authToken?: string) => Promise<boolean>
+  pauseDownload?: (url: string) => Promise<boolean>
+  resumeDownload?: (url: string) => Promise<boolean>
+  cancelDownload?: (url: string) => Promise<boolean>
+  onDownloadProgress?: (callback: (data: ComfyDownloadProgress) => void) => () => void
+  reportTheme?: (bg: string, text: string) => void
+  Terminal?: ComfyDesktop2TerminalBridge
+  Logs?: ComfyDesktop2LogsBridge
+  Telemetry?: ComfyDesktop2TelemetryBridge
 }
+/**
+ * The `-?` mapper intentionally requires every top-level bridge member.
+ * Adding an optional top-level member to `ComfyDesktop2Bridge` is therefore a
+ * breaking change for implementations of this type. Optional members of nested
+ * bridge types remain optional because the mapper is not recursive.
+ */
 export type ComfyDesktop2BridgeImplementation = {
-    [K in keyof ComfyDesktop2Bridge]-?: NonNullable<ComfyDesktop2Bridge[K]>;
-};
+  [K in keyof ComfyDesktop2Bridge]-?: NonNullable<ComfyDesktop2Bridge[K]>
+}

package/index.d.ts

@@ -1 +1 @@
-export * from './comfyDesktopBridge'
+export * from './comfyDesktopBridge.js'

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@comfyorg/comfyui-desktop-bridge-types",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeScript definitions for the Comfy Desktop hosted frontend bridge",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
   "files": [
-    "comfyDesktopBridge.d.ts",
-    "index.d.ts",
+    "*.d.ts",
     "index.js"
   ],
   "publishConfig": {