@comfyorg/sdk 0.1.0

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

@@ -0,0 +1,528 @@
+export type ClientOptions = {
+    baseUrl: 'http://127.0.0.1:8189' | 'https://api.comfy.org' | 'https://{deployment}.comfy.org' | (string & {});
+};
+/**
+ * A user-owned record identified by a server-assigned UUID, backing an immutable blob whose content carries a server-computed blake3 hash. `hash` may be computed lazily: an asset record (and its retrievable bytes) can exist before its hash is filled in.
+ */
+export type Asset = {
+    id: string;
+    /**
+     * `blake3:<hex>`; null while lazily computed.
+     */
+    hash: string | null;
+    size_bytes: number;
+    content_type: string;
+    file_path?: string | null;
+    /**
+     * On create responses: distinguishes a brand-new blob (true) from a dedup hit against bytes the platform already had (false).
+     */
+    created_new?: boolean;
+    created_at: string;
+    /**
+     * Short-lived content URL (signed, or proxy-served).
+     */
+    url: string;
+    url_expires_at: string;
+};
+/**
+ * One execution of a workflow. Durable from creation until `expires_at`; `outputs` populates incrementally during execution.
+ */
+export type Job = {
+    id: string;
+    status: JobStatus;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+    /**
+     * Retention deadline — a platform property, not an API constant.
+     */
+    expires_at: string;
+    queue_position: number | null;
+    /**
+     * The latest progress snapshot; same data the SSE stream pushes.
+     */
+    progress: Progress | null;
+    outputs: Array<Output>;
+    error: JobError | null;
+    /**
+     * Values are nullable (a metric not yet available — e.g. `execution_ms` before a job starts running — is `null`, not omitted); the example below is deliberately all-non-null purely to work around a Spectral/nimma lint-tooling crash on a literal `null` inside a schema `example` combined with `additionalProperties.nullable: true` — the schema itself is unchanged and still allows null values at runtime.
+     */
+    metrics?: {
+        [key: string]: number | null;
+    };
+    urls: JobUrls;
+};
+/**
+ * Lifecycle: queued → running → succeeded | failed | expired;
+ * a cancel request moves running → canceling → canceled.
+ * Terminal states: succeeded, canceled, failed, expired.
+ *
+ */
+export type JobStatus = 'queued' | 'running' | 'succeeded' | 'canceling' | 'canceled' | 'failed' | 'expired';
+/**
+ * Embedded follow-up links — follow these, don't build URLs.
+ */
+export type JobUrls = {
+    self: string;
+    events: string;
+    cancel: string;
+};
+/**
+ * Server-computed progress snapshot (node-count and sampler-step weighted). Complete per snapshot — one fully re-syncs a client.
+ */
+export type Progress = {
+    /**
+     * Overall fraction, server-computed.
+     */
+    value: number;
+    nodes_done: number;
+    nodes_total: number;
+    current_node?: string | null;
+    current_node_class?: string | null;
+    step?: number | null;
+    steps?: number | null;
+    message?: string | null;
+};
+/**
+ * A committed job output. Outputs are assets: `id` is the asset UUID, retrievable via GET /api/v2/assets/{id} for as long as the job is retained. `hash` is lazily computed and may be null on the retrieval hot path.
+ */
+export type Output = {
+    node_id: string;
+    name: string;
+    type: OutputType;
+    content_type: string;
+    size_bytes: number;
+    /**
+     * Asset UUID.
+     */
+    id: string;
+    /**
+     * `blake3:<hex>`; null until lazily computed.
+     */
+    hash: string | null;
+    url: string;
+    url_expires_at: string;
+};
+/**
+ * Normalized output kind — nothing silently dropped.
+ */
+export type OutputType = 'image' | 'video' | 'audio' | 'text' | 'file' | 'latent';
+/**
+ * Execution failure detail, carried in `job.error` (not an HTTP error).
+ */
+export type JobError = {
+    code: string;
+    message: string;
+    node_id?: string | null;
+    class_type?: string | null;
+    traceback?: string | null;
+};
+/**
+ * Shared error envelope with machine-readable codes. Core codes (v1):
+ * `invalid_workflow` (422), `workflow_format_ui` (422),
+ * `missing_asset` (422), `hash_mismatch` (409), `blob_not_found`
+ * (404), `idempotency_key_reuse` (422),
+ * `queue_full` (429 + Retry-After), `insufficient_credits` (402),
+ * `not_found` (404), `unauthorized` (401), `forbidden` (403).
+ *
+ */
+export type ErrorEnvelope = {
+    error: {
+        code: string;
+        message: string;
+        details?: {
+            [key: string]: unknown;
+        } | null;
+    };
+};
+/**
+ * Client-generated UUID (recommended). Single-use: the first request to present a key is processed; any later request with the same key is rejected `422` `idempotency_key_reuse` (reject-on-duplicate, no response replay). Keys expire after 24h.
+ */
+export type IdempotencyKey = string;
+export type JobId = string;
+export type AssetId = string;
+/**
+ * Content hash, written `blake3:<hex>`.
+ */
+export type BlakeHash = string;
+export type PostAssetsData = {
+    body: {
+        /**
+         * The raw bytes.
+         */
+        file: Blob | File;
+        content_type: string;
+        /**
+         * Placement path / filename (global-namespace-root form, e.g. `photo.png` or `models/checkpoints/x.safetensors`).
+         */
+        file_path: string;
+        /**
+         * Optional client-computed blake3 (`blake3:<hex>`). Verified against the server-computed hash; mismatch is rejected with 409 `hash_mismatch` and no asset is minted.
+         */
+        expected_hash?: string;
+        /**
+         * Category tags (e.g. `input`).
+         */
+        tags?: Array<string>;
+    };
+    headers?: {
+        /**
+         * Client-generated UUID (recommended). Single-use: the first request to present a key is processed; any later request with the same key is rejected `422` `idempotency_key_reuse` (reject-on-duplicate, no response replay). Keys expire after 24h.
+         */
+        'Idempotency-Key'?: string;
+    };
+    path?: never;
+    query?: never;
+    url: '/api/v2/assets';
+};
+export type PostAssetsErrors = {
+    /**
+     * `unauthorized` — missing or invalid credentials.
+     */
+    401: ErrorEnvelope;
+    /**
+     * `forbidden` — authenticated but not allowed.
+     */
+    403: ErrorEnvelope;
+    /**
+     * `hash_mismatch`.
+     */
+    409: ErrorEnvelope;
+    /**
+     * `idempotency_key_reuse` or validation failure.
+     */
+    422: ErrorEnvelope;
+    /**
+     * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
+     */
+    500: ErrorEnvelope;
+};
+export type PostAssetsError = PostAssetsErrors[keyof PostAssetsErrors];
+export type PostAssetsResponses = {
+    /**
+     * Bytes deduped to an existing blob; asset minted over it.
+     */
+    200: Asset;
+    /**
+     * New blob stored; asset minted.
+     */
+    201: Asset;
+};
+export type PostAssetsResponse = PostAssetsResponses[keyof PostAssetsResponses];
+export type AssetFromHashData = {
+    body: {
+        hash: string;
+        file_path?: string;
+        tags?: Array<string>;
+    };
+    path?: never;
+    query?: never;
+    url: '/api/v2/assets/from-hash';
+};
+export type AssetFromHashErrors = {
+    /**
+     * `unauthorized` — missing or invalid credentials.
+     */
+    401: ErrorEnvelope;
+    /**
+     * `forbidden` — authenticated but not allowed.
+     */
+    403: ErrorEnvelope;
+    /**
+     * `blob_not_found` — no blob the caller may mint from.
+     */
+    404: ErrorEnvelope;
+    /**
+     * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
+     */
+    500: ErrorEnvelope;
+};
+export type AssetFromHashError = AssetFromHashErrors[keyof AssetFromHashErrors];
+export type AssetFromHashResponses = {
+    /**
+     * An identical reference already existed; returned as-is.
+     */
+    200: Asset;
+    /**
+     * Asset minted over the existing blob.
+     */
+    201: Asset;
+};
+export type AssetFromHashResponse = AssetFromHashResponses[keyof AssetFromHashResponses];
+export type HeadAssetByHashData = {
+    body?: never;
+    path: {
+        /**
+         * Content hash, written `blake3:<hex>`.
+         */
+        hash: string;
+    };
+    query?: never;
+    url: '/api/v2/assets/by-hash/{hash}';
+};
+export type HeadAssetByHashErrors = {
+    /**
+     * `unauthorized` — missing or invalid credentials.
+     */
+    401: ErrorEnvelope;
+    /**
+     * No blob the caller may mint from.
+     */
+    404: unknown;
+    /**
+     * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
+     */
+    500: ErrorEnvelope;
+};
+export type HeadAssetByHashError = HeadAssetByHashErrors[keyof HeadAssetByHashErrors];
+export type HeadAssetByHashResponses = {
+    /**
+     * Blob present and mintable by the caller.
+     */
+    200: unknown;
+};
+export type GetAssetData = {
+    body?: never;
+    path: {
+        id: string;
+    };
+    query?: never;
+    url: '/api/v2/assets/{id}';
+};
+export type GetAssetErrors = {
+    /**
+     * `unauthorized` — missing or invalid credentials.
+     */
+    401: ErrorEnvelope;
+    /**
+     * `forbidden` — authenticated but not allowed.
+     */
+    403: ErrorEnvelope;
+    /**
+     * `not_found`.
+     */
+    404: ErrorEnvelope;
+    /**
+     * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
+     */
+    500: ErrorEnvelope;
+};
+export type GetAssetError = GetAssetErrors[keyof GetAssetErrors];
+export type GetAssetResponses = {
+    /**
+     * The asset.
+     */
+    200: Asset;
+};
+export type GetAssetResponse = GetAssetResponses[keyof GetAssetResponses];
+export type GetAssetContentData = {
+    body?: never;
+    headers?: {
+        /**
+         * Standard HTTP range, e.g. `bytes=0-1048575`.
+         */
+        Range?: string;
+    };
+    path: {
+        id: string;
+    };
+    query?: never;
+    url: '/api/v2/assets/{id}/content';
+};
+export type GetAssetContentErrors = {
+    /**
+     * `unauthorized` — missing or invalid credentials.
+     */
+    401: ErrorEnvelope;
+    /**
+     * `forbidden` — authenticated but not allowed.
+     */
+    403: ErrorEnvelope;
+    /**
+     * `not_found`.
+     */
+    404: ErrorEnvelope;
+    /**
+     * Range not satisfiable.
+     */
+    416: unknown;
+    /**
+     * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
+     */
+    500: ErrorEnvelope;
+};
+export type GetAssetContentError = GetAssetContentErrors[keyof GetAssetContentErrors];
+export type GetAssetContentResponses = {
+    /**
+     * The full content.
+     */
+    200: Blob | File;
+    /**
+     * Partial content for a ranged request.
+     */
+    206: Blob | File;
+};
+export type GetAssetContentResponse = GetAssetContentResponses[keyof GetAssetContentResponses];
+export type PostJobsData = {
+    body: {
+        /**
+         * API-format workflow graph, verbatim.
+         */
+        workflow: {
+            [key: string]: unknown;
+        };
+    };
+    headers?: {
+        /**
+         * Client-generated UUID (recommended). Single-use: the first request to present a key is processed; any later request with the same key is rejected `422` `idempotency_key_reuse` (reject-on-duplicate, no response replay). Keys expire after 24h.
+         */
+        'Idempotency-Key'?: string;
+    };
+    path?: never;
+    query?: never;
+    url: '/api/v2/jobs';
+};
+export type PostJobsErrors = {
+    /**
+     * `unauthorized` — missing or invalid credentials.
+     */
+    401: ErrorEnvelope;
+    /**
+     * `insufficient_credits` (Cloud / serverless only).
+     */
+    402: ErrorEnvelope;
+    /**
+     * `forbidden` — authenticated but not allowed.
+     */
+    403: ErrorEnvelope;
+    /**
+     * `invalid_workflow` (with per-node details), `workflow_format_ui`, `missing_asset`, or `idempotency_key_reuse`.
+     */
+    422: ErrorEnvelope;
+    /**
+     * `queue_full` — bounded queue depth reached.
+     */
+    429: ErrorEnvelope;
+    /**
+     * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
+     */
+    500: ErrorEnvelope;
+};
+export type PostJobsError = PostJobsErrors[keyof PostJobsErrors];
+export type PostJobsResponses = {
+    /**
+     * Job created and queued.
+     */
+    201: Job;
+};
+export type PostJobsResponse = PostJobsResponses[keyof PostJobsResponses];
+export type GetJobData = {
+    body?: never;
+    path: {
+        id: string;
+    };
+    query?: never;
+    url: '/api/v2/jobs/{id}';
+};
+export type GetJobErrors = {
+    /**
+     * `unauthorized` — missing or invalid credentials.
+     */
+    401: ErrorEnvelope;
+    /**
+     * `forbidden` — authenticated but not allowed.
+     */
+    403: ErrorEnvelope;
+    /**
+     * `not_found`.
+     */
+    404: ErrorEnvelope;
+    /**
+     * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
+     */
+    500: ErrorEnvelope;
+};
+export type GetJobError = GetJobErrors[keyof GetJobErrors];
+export type GetJobResponses = {
+    /**
+     * The job.
+     */
+    200: Job;
+};
+export type GetJobResponse = GetJobResponses[keyof GetJobResponses];
+export type GetJobEventsData = {
+    body?: never;
+    path: {
+        id: string;
+    };
+    query?: never;
+    url: '/api/v2/jobs/{id}/events';
+};
+export type GetJobEventsErrors = {
+    /**
+     * `unauthorized` — missing or invalid credentials.
+     */
+    401: ErrorEnvelope;
+    /**
+     * `forbidden` — authenticated but not allowed.
+     */
+    403: ErrorEnvelope;
+    /**
+     * `not_found`.
+     */
+    404: ErrorEnvelope;
+    /**
+     * `too_many_streams` — the caller already has the maximum number of concurrent GET .../events streams open. Close an existing stream (or wait for one to reach a terminal status) before opening another; GET /api/v2/jobs/{id} remains available as a plain poll regardless of this limit.
+     */
+    429: ErrorEnvelope;
+    /**
+     * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
+     */
+    500: ErrorEnvelope;
+    /**
+     * `not_implemented` — this deployment does not yet serve live event streaming. GET /api/v2/jobs/{id} remains available as a plain poll in the meantime.
+     */
+    501: ErrorEnvelope;
+};
+export type GetJobEventsError = GetJobEventsErrors[keyof GetJobEventsErrors];
+export type GetJobEventsResponses = {
+    /**
+     * Stream of `event:`/`data:` frames. Data payloads are the JSON schemas listed in x-sse-events.
+     */
+    200: string;
+};
+export type GetJobEventsResponse = GetJobEventsResponses[keyof GetJobEventsResponses];
+export type CancelJobData = {
+    body?: never;
+    path: {
+        id: string;
+    };
+    query?: never;
+    url: '/api/v2/jobs/{id}/cancel';
+};
+export type CancelJobErrors = {
+    /**
+     * `unauthorized` — missing or invalid credentials.
+     */
+    401: ErrorEnvelope;
+    /**
+     * `forbidden` — authenticated but not allowed.
+     */
+    403: ErrorEnvelope;
+    /**
+     * `not_found`.
+     */
+    404: ErrorEnvelope;
+    /**
+     * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
+     */
+    500: ErrorEnvelope;
+};
+export type CancelJobError = CancelJobErrors[keyof CancelJobErrors];
+export type CancelJobResponses = {
+    /**
+     * Current job state.
+     */
+    200: Job;
+};
+export type CancelJobResponse = CancelJobResponses[keyof CancelJobResponses];

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

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};