@comfyorg/sdk 0.1.0 → 0.1.1

package/README.md

@@ -79,6 +79,23 @@ await job.wait(); // poll to terminal (adaptive backoff); or call job.refresh()
 console.log(job.status, job.outputs);
 ```
 
+## Partner (API) node auth
+
+Workflows that use partner/API nodes (Gemini, etc.) need a Comfy API key to
+authenticate them. Pass it per submit with `apiKey`. This is **not** the same as
+the credential you construct `Comfy` with: the constructor key authenticates
+_you_ to the server, while this one authenticates the partner nodes _inside_ the
+workflow (it is often the same `comfyui-…` key):
+
+```ts
+const job = await client.run(wf, { apiKey: "comfyui-…" });
+// or: await client.submit(wf, { apiKey: "comfyui-…" });
+```
+
+The SDK sends it once as `extra_data.api_key_comfy_org` alongside the workflow —
+one key authenticates every partner node in the graph. It is never logged or
+persisted by the SDK. Omit `apiKey` and no `extra_data` is sent at all.
+
 ## Assets and `core/ASSET`
 
 `client.assets.fromFile(path)` / `client.assets.fromBytes(data, options)`

package/dist/low/generated/types.gen.d.ts

@@ -371,6 +371,15 @@ export type PostJobsData = {
         workflow: {
             [key: string]: unknown;
         };
+        /**
+         * Optional typed extras submitted alongside the workflow. Closed: only the enumerated properties are accepted.
+         */
+        extra_data?: {
+            /**
+             * API key for partner (API) nodes.
+             */
+            api_key_comfy_org?: string;
+        };
     };
     headers?: {
         /**

package/dist/low/generated/zod.gen.d.ts

@@ -253,6 +253,9 @@ export declare const zGetAssetContentPath: z.ZodObject<{
 export declare const zGetAssetContentResponse: z.ZodString;
 export declare const zPostJobsBody: z.ZodObject<{
     workflow: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    extra_data: z.ZodOptional<z.ZodObject<{
+        api_key_comfy_org: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const zPostJobsHeaders: z.ZodObject<{
     'Idempotency-Key': z.ZodOptional<z.ZodString>;

package/dist/low/generated/zod.gen.js

@@ -172,7 +172,10 @@ export const zGetAssetContentPath = z.object({
  */
 export const zGetAssetContentResponse = z.string();
 export const zPostJobsBody = z.object({
-    workflow: z.record(z.string(), z.unknown())
+    workflow: z.record(z.string(), z.unknown()),
+    extra_data: z.object({
+        api_key_comfy_org: z.string().optional()
+    }).optional()
 });
 export const zPostJobsHeaders = z.object({
     'Idempotency-Key': z.string().optional()

package/dist/low/transport.d.ts

@@ -25,7 +25,7 @@
  * the Python SDK (its `AsyncComfyLow`; there is no sync variant here — see
  * the package README for why).
  */
-import type { Asset, Job } from "./generated/types.gen.js";
+import type { Asset, Job, PostJobsData } from "./generated/types.gen.js";
 import { type RawEvent } from "./sse.js";
 export interface RequestOptions {
     headers?: Record<string, string>;
@@ -100,9 +100,14 @@ export declare class ComfyLow {
         range?: readonly [number, number];
         signal?: AbortSignal;
     }): Promise<Response>;
-    /** `POST /api/v2/jobs`. */
+    /**
+     * `POST /api/v2/jobs`. `extraData` (e.g. the partner-node API key) is a
+     * sibling of `workflow` on the wire, per the spec's closed `extra_data`
+     * object; omitted entirely when not provided, never sent empty.
+     */
     postJobs(workflow: Record<string, unknown>, options?: {
         idempotencyKey?: string;
+        extraData?: PostJobsData["body"]["extra_data"];
         signal?: AbortSignal;
     }): Promise<Job>;
     /** `GET /api/v2/jobs/{id}` (or an absolute self link). */

package/dist/low/transport.js

@@ -210,13 +210,22 @@ export class ComfyLow {
         return response;
     }
     // -- jobs -----------------------------------------------------------------
-    /** `POST /api/v2/jobs`. */
+    /**
+     * `POST /api/v2/jobs`. `extraData` (e.g. the partner-node API key) is a
+     * sibling of `workflow` on the wire, per the spec's closed `extra_data`
+     * object; omitted entirely when not provided, never sent empty.
+     */
     async postJobs(workflow, options = {}) {
         const headers = {};
         if (options.idempotencyKey) {
             headers["Idempotency-Key"] = options.idempotencyKey;
         }
         const json = { workflow };
+        // Only attach a non-empty extra_data — never serialize an empty object onto
+        // the wire (mirrors the Python low layer's truthy guard).
+        if (options.extraData && Object.keys(options.extraData).length > 0) {
+            json.extra_data = options.extraData;
+        }
         const response = await this.request("POST", "/jobs", { headers, json, signal: options.signal });
         return this.parseOrRaise(response, [201]);
     }

package/dist/sdk/client.d.ts

@@ -57,14 +57,22 @@ export declare class Comfy {
      * idempotent, pass an explicit `idempotencyKey` and reuse it. Note a reused
      * key is *rejected*, not replayed: on reuse, catch the error and poll/list
      * for the job the first attempt already created.
+     *
+     * Pass `apiKey` to authenticate partner (API) nodes in the workflow (for
+     * example Gemini) — it is sent once, as `extra_data.api_key_comfy_org`
+     * alongside the workflow, and is unrelated to the `Idempotency-Key`: it
+     * does not affect idempotency and is never persisted or logged by this
+     * SDK. Omit it and no `extra_data` is sent at all.
      */
     submit(workflow: Workflow, options?: {
         idempotencyKey?: string;
+        apiKey?: string;
         signal?: AbortSignal;
     }): Promise<Job>;
     /** Submit, then poll to terminal (authoritative). Throws on failure. */
     run(workflow: Workflow, options?: {
         timeoutMs?: number;
+        apiKey?: string;
         signal?: AbortSignal;
     }): Promise<Job>;
 }

package/dist/sdk/client.js

@@ -77,16 +77,26 @@ export class Comfy {
      * idempotent, pass an explicit `idempotencyKey` and reuse it. Note a reused
      * key is *rejected*, not replayed: on reuse, catch the error and poll/list
      * for the job the first attempt already created.
+     *
+     * Pass `apiKey` to authenticate partner (API) nodes in the workflow (for
+     * example Gemini) — it is sent once, as `extra_data.api_key_comfy_org`
+     * alongside the workflow, and is unrelated to the `Idempotency-Key`: it
+     * does not affect idempotency and is never persisted or logged by this
+     * SDK. Omit it and no `extra_data` is sent at all.
      */
     async submit(workflow, options = {}) {
         guardUiFormat(workflow);
         const graph = await this.materialize(workflow, options.signal);
         const key = options.idempotencyKey ?? newIdempotencyKey();
+        // A falsy apiKey (undefined or "") means "no key" — send no extra_data,
+        // matching the Python SDK's behavior so the two stay in lockstep.
+        const extraData = options.apiKey ? { api_key_comfy_org: options.apiKey } : undefined;
         const deadline = Date.now() + QUEUE_RETRY_BUDGET_MS;
         for (;;) {
             try {
                 const job = await this.low.postJobs(graph, {
                     idempotencyKey: key,
+                    extraData,
                     signal: options.signal,
                 });
                 return new Job(this.low, job);
@@ -105,7 +115,7 @@ export class Comfy {
     }
     /** Submit, then poll to terminal (authoritative). Throws on failure. */
     async run(workflow, options = {}) {
-        const job = await this.submit(workflow, { signal: options.signal });
+        const job = await this.submit(workflow, { apiKey: options.apiKey, signal: options.signal });
         return options.timeoutMs === undefined
             ? job.result(options.signal)
             : runWithTimeout(job, options.timeoutMs, options.signal);

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@comfyorg/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "TypeScript SDK for running ComfyUI workflows via the Comfy API v2 (self-hosted, Comfy Cloud, serverless).",
+  "homepage": "https://github.com/Comfy-Org/ComfyTypeScriptSDK#readme",
+  "bugs": {
+    "url": "https://github.com/Comfy-Org/ComfyTypeScriptSDK/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Comfy-Org/ComfyTypeScriptSDK.git"
+  },
   "files": [
     "dist"
   ],
@@ -19,17 +27,6 @@
       "default": "./dist/low/index.js"
     }
   },
-  "scripts": {
-    "build": "tsc",
-    "generate": "openapi-ts",
-    "lint": "oxlint .",
-    "format": "oxfmt --write .",
-    "format:check": "oxfmt --check .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "check:spec-drift": "node scripts/check-spec-drift.mjs"
-  },
   "dependencies": {
     "eventsource-parser": "^3.0.0",
     "hash-wasm": "^4.11.0",
@@ -48,5 +45,15 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@11.13.0"
-}
+  "scripts": {
+    "build": "tsc",
+    "generate": "openapi-ts",
+    "lint": "oxlint .",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "check:spec-drift": "node scripts/check-spec-drift.mjs"
+  }
+}