@sogni-ai/sogni-client 5.56.2 → 5.57.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [5.57.0](https://github.com/Sogni-AI/sogni-client/compare/v5.56.3...v5.57.0) (2026-09-26)
+
+
+### Features
+
+* **projects:** fetch a project's results by id and list recent completed projects ([89cd46d](https://github.com/Sogni-AI/sogni-client/commit/89cd46d4991fcddc83737d2abc3a0106d3734660))
+
+## [5.56.3](https://github.com/Sogni-AI/sogni-client/compare/v5.56.2...v5.56.3) (2026-09-26)
+
+
+### Bug Fixes
+
+* **projects:** know the live Wan sound-to-video and Qwen3 TTS ids as media ([f621acb](https://github.com/Sogni-AI/sogni-client/commit/f621acb974de81659a958b594f0a5c52c4d957e4))
+
 ## [5.56.2](https://github.com/Sogni-AI/sogni-client/compare/v5.56.1...v5.56.2) (2026-09-26)
 
 

package/README.md

@@ -525,6 +525,30 @@ when they finish.
 Recovery is per app instance: the server hands projects back to the `appId` that created them, so
 persist your `appId` (browsers: `localStorage`) and reuse it across reloads.
 
+#### Results after you stopped waiting
+
+The socket holds a project that finished while its client was disconnected for one hour. A client
+that restarts, or a script or agent that exits before its projects finish, can still collect them:
+
+- `sogni.projects.getResult(id)` returns a project's state and its renders at any time: while it is
+  queued (with the server's `waitingReason`, which says whether the account's own plan concurrency is
+  holding it or it is waiting for a worker) and after it finished, with signed download URLs for the
+  completed renders. Pass `{ kind: 'video' }` (or `image`, `audio`, `model`) when you know what it
+  produces and the model is not in this client's catalog.
+- `sogni.projects.listRecent({ since })` lists this account's recently completed media projects,
+  newest first, from the durable history (up to 7 days back, 24 hours by default), including ones
+  that finished while no client was connected.
+
+```typescript
+for (const project of await sogni.projects.listRecent({ since: Date.now() - 6 * 3600_000 })) {
+  const result = await sogni.projects.getResult(project.id);
+  for (const job of result.jobs) if (job.url) console.log(project.modelName, job.url);
+}
+
+const pending = await sogni.projects.getResult(projectId);
+if (!pending.finished) console.log(pending.status, pending.waitingReason?.message);
+```
+
 ### Project parameters
 
 Here is a full list of project parameters that you can use:

package/dist/Projects/index.d.ts

@@ -7,6 +7,7 @@ import { AvailableLorasParams, LoraCatalog, LoraCatalogEntry, LoraConstraints }
 import PersonalLoras from './PersonalLoras.js';
 import { ProjectApiEvents, type ProjectSyncReason, type ProjectSyncResult } from './types/events.js';
 import { RawProject } from './types/RawProject.js';
+import type { WaitingReason } from './types/WaitingReason.js';
 import { SupernetType } from '../ApiClient/WebSocketClient/types.js';
 import { type ResultMediaEvidence, type ResultMediaKind } from './utils/index.js';
 import { TokenType } from '../types/token.js';
@@ -62,6 +63,86 @@ export type ProjectStatusSnapshot = Partial<Omit<RawProject, 'status' | 'workerJ
     workerJobs: RawProject['workerJobs'];
     completedWorkerJobs: RawProject['completedWorkerJobs'];
 };
+/**
+ * One render of a project returned by {@link ProjectsApi.getResult}.
+ */
+export interface ProjectResultJob {
+    /** The render's result id (the `imgID` of its events). */
+    id: string;
+    /**
+     * `completed`, `failed` or `canceled` once it has finished; otherwise the
+     * worker job's in-flight status (`queued`, `assigned`, `jobStarted`, ...).
+     */
+    status: string;
+    /** Why a failed or cancelled render ended, e.g. `genfailure` or `artistCanceled`. */
+    reason?: string;
+    /** What the result is, when it is known. */
+    kind?: ResultMediaKind;
+    /** Signed download URL for a completed render's media. It expires; fetch a new one when it does. */
+    url?: string;
+    /**
+     * Why a completed render has no `url`: `sensitiveContent` when the Sensitive
+     * Content Filter withheld it, `unknownMediaKind` when neither the model nor
+     * the result says what media it is, `downloadUrlFailed` when the API refused
+     * or failed to sign one (retry later).
+     */
+    urlUnavailable?: 'sensitiveContent' | 'unknownMediaKind' | 'downloadUrlFailed';
+    /** Seed the render used, when recorded. */
+    seed?: number;
+}
+/**
+ * One of this account's projects as {@link ProjectsApi.getResult} sees it:
+ * its current state, why it is still waiting if it is, and every render with
+ * a download URL for the ones that completed.
+ */
+export interface ProjectResult {
+    id: string;
+    status: ProjectLookupStatus;
+    /** `true` for `completed`, `failed` and `canceled`. */
+    finished: boolean;
+    modelId?: string;
+    /**
+     * While it is still queued: the server's explanation, e.g. the account's own
+     * plan concurrency limit (`concurrency_limit`, `model_concurrency_limit`)
+     * rather than a shortage of workers (`no_workers`). Absent when the server
+     * did not report one.
+     */
+    waitingReason?: WaitingReason | null;
+    jobs: ProjectResultJob[];
+}
+/** A render of a project returned by {@link ProjectsApi.listRecent}. */
+export interface RecentProjectJob {
+    /** The render's result id; pass the project id to {@link ProjectsApi.getResult} for its URL. */
+    id: string;
+    status: string;
+    /** The Sensitive Content Filter withheld this render's media. */
+    sensitiveContentWithheld: boolean;
+    /** Milliseconds since the epoch. */
+    finishedAt?: number;
+}
+/** A project returned by {@link ProjectsApi.listRecent}. */
+export interface RecentProject {
+    id: string;
+    modelId?: string;
+    modelName?: string;
+    /** The app that submitted it, when recorded (e.g. `sogni-creative-agent-skill`). */
+    appSource?: string;
+    /** When its latest render finished, in milliseconds since the epoch. */
+    finishedAt?: number;
+    jobs: RecentProjectJob[];
+}
+export interface ListRecentProjectsOptions {
+    /**
+     * Oldest finish time to include, as a `Date` or milliseconds since the epoch.
+     * Defaults to 24 hours ago. The history keeps 7 days, so anything older is
+     * read as 7 days ago.
+     */
+    since?: Date | number;
+    /** Renders to read, 1-100 (default 50). Projects are grouped from these. */
+    limit?: number;
+    /** Only projects submitted by this app source. */
+    appSource?: string;
+}
 declare class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     private _personalLoras?;
     /** Import, inspect, discover, and remove the signed-in account's personal LoRAs. */
@@ -418,6 +499,62 @@ declare class ProjectsApi extends ApiGroup<ProjectApiEvents> {
      * @param projectId
      */
     getStatus(projectId: string): Promise<ProjectStatusSnapshot>;
+    /**
+     * State and results of one of this account's projects by id, whenever it is
+     * asked: while it is queued or rendering, and after it finished, including
+     * one that finished while this client was offline, or after it stopped
+     * waiting, or long after the socket stopped holding it for a reconnect.
+     *
+     * Completed renders come back with signed download URLs, minted the same way
+     * a live result's are. A queued project carries the server's `waitingReason`,
+     * which says whether it is held by the account's own plan concurrency or is
+     * waiting for a worker. Needs an authenticated client; another account's or
+     * an unknown project rejects with a 404 `ApiError`.
+     *
+     * @example
+     * ```ts
+     * const result = await sogni.projects.getResult(projectId);
+     * if (result.finished) {
+     *   for (const job of result.jobs) if (job.url) console.log(job.url);
+     * } else {
+     *   console.log(result.status, result.waitingReason?.message);
+     * }
+     * ```
+     * @param projectId
+     * @param options.kind - What the project produces, when the caller knows it
+     *   (`image`, `video`, `audio`, `model`). Used only when neither the model
+     *   catalog nor the stored result says, so a URL is never minted from the
+     *   wrong endpoint.
+     */
+    getResult(projectId: string, options?: {
+        kind?: ResultMediaKind;
+    }): Promise<ProjectResult>;
+    /**
+     * This account's recently completed projects that produced media, newest
+     * first, read from the durable history rather than the socket. It includes
+     * projects that finished while no client was connected, and ones the socket
+     * has stopped holding for a reconnect (it keeps a finished project for one
+     * hour). Pass a project's id to {@link getResult} for its download URLs.
+     *
+     * Reaches back at most 7 days. Needs a signed-in account.
+     *
+     * @example
+     * ```ts
+     * const recent = await sogni.projects.listRecent({ since: Date.now() - 6 * 3600_000 });
+     * for (const project of recent) {
+     *   const result = await sogni.projects.getResult(project.id);
+     * }
+     * ```
+     */
+    listRecent(options?: ListRecentProjectsOptions): Promise<RecentProject[]>;
+    private _accountAddress?;
+    /**
+     * How {@link listRecent} learns the signed-in account's address. Set by
+     * `SogniClient`, which owns the account.
+     * @internal
+     */
+    _setAccountAddressResolver(resolve: () => Promise<string | undefined>): void;
+    private _resolveAccountAddress;
     /**
      * Ids of this account's projects that are currently live on the socket,
      * including ones still queued with no worker assigned.

package/dist/Projects/index.js

@@ -313,6 +313,18 @@ const RESUBMIT_RECONNECT_TIMEOUT_MS = 60000;
 const MISSING_PROJECT_ATTEMPTS = 4;
 const MISSING_PROJECT_RETRY_MS = 2500;
 const IN_FLIGHT_LOOKUP_STATUSES = new Set(['pending', 'queued', 'processing']);
+const RECENT_PROJECTS_DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000;
+// The history API refuses a media-only lookup reaching back more than 7 days;
+// stay a minute inside it so a slow clock cannot turn a 7-day request into a 400.
+const RECENT_PROJECTS_MAX_WINDOW_MS = 7 * 24 * 60 * 60 * 1000 - 60 * 1000;
+/** A worker job's status in the names {@link ProjectResultJob} uses. */
+function resultJobStatus(job) {
+    if (job.status === 'jobCompleted')
+        return 'completed';
+    if (job.status === 'jobError')
+        return job.reason === 'artistCanceled' ? 'canceled' : 'failed';
+    return job.status || 'unknown';
+}
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 class ProjectsApi extends ApiGroup_js_1.default {
     /** Import, inspect, discover, and remove the signed-in account's personal LoRAs. */
@@ -2132,6 +2144,164 @@ class ProjectsApi extends ApiGroup_js_1.default {
             return data.project;
         });
     }
+    /**
+     * State and results of one of this account's projects by id, whenever it is
+     * asked: while it is queued or rendering, and after it finished, including
+     * one that finished while this client was offline, or after it stopped
+     * waiting, or long after the socket stopped holding it for a reconnect.
+     *
+     * Completed renders come back with signed download URLs, minted the same way
+     * a live result's are. A queued project carries the server's `waitingReason`,
+     * which says whether it is held by the account's own plan concurrency or is
+     * waiting for a worker. Needs an authenticated client; another account's or
+     * an unknown project rejects with a 404 `ApiError`.
+     *
+     * @example
+     * ```ts
+     * const result = await sogni.projects.getResult(projectId);
+     * if (result.finished) {
+     *   for (const job of result.jobs) if (job.url) console.log(job.url);
+     * } else {
+     *   console.log(result.status, result.waitingReason?.message);
+     * }
+     * ```
+     * @param projectId
+     * @param options.kind - What the project produces, when the caller knows it
+     *   (`image`, `video`, `audio`, `model`). Used only when neither the model
+     *   catalog nor the stored result says, so a URL is never minted from the
+     *   wrong endpoint.
+     */
+    getResult(projectId_1) {
+        return __awaiter(this, arguments, void 0, function* (projectId, options = {}) {
+            var _a, _b, _c, _d, _e;
+            const assertSession = (0, requestSession_js_1.captureRequestSession)(this.client.auth);
+            const snapshot = yield this.getStatus(projectId);
+            assertSession();
+            const modelId = (_a = snapshot.model) === null || _a === void 0 ? void 0 : _a.id;
+            // The stored record's model carries its media type even though ProjectModel does not declare it.
+            const recordType = (_b = snapshot.model) === null || _b === void 0 ? void 0 : _b.type;
+            const projectType = typeof recordType === 'string' ? recordType : undefined;
+            const jobs = [];
+            const seen = new Set();
+            for (const job of [...(snapshot.completedWorkerJobs || []), ...(snapshot.workerJobs || [])]) {
+                const id = job.imgID || job.id;
+                if (!id || seen.has(id))
+                    continue;
+                seen.add(id);
+                const status = resultJobStatus(job);
+                const entry = { id, status };
+                if (status !== 'completed' && job.reason)
+                    entry.reason = job.reason;
+                if (typeof job.seedUsed === 'number' && job.seedUsed >= 0)
+                    entry.seed = job.seedUsed;
+                if (status === 'completed') {
+                    // Same rule as a live result: withheld only when the filter fired and
+                    // no advisory label says the media was delivered anyway.
+                    if (job.triggeredNSFWFilter === true && job.nsfwDetected !== true) {
+                        entry.urlUnavailable = 'sensitiveContent';
+                    }
+                    else if (typeof job.resultUrl === 'string' && job.resultUrl) {
+                        entry.url = job.resultUrl;
+                    }
+                    else {
+                        const result = (0, index_js_2.resultMediaEvidence)(Object.assign(Object.assign({}, (job.result || {})), { outputFormat: (_c = job.outputFormat) !== null && _c !== void 0 ? _c : (_d = job.result) === null || _d === void 0 ? void 0 : _d.outputFormat }));
+                        const kind = (_e = this._resultMediaKind({ modelId, projectType, result })) !== null && _e !== void 0 ? _e : options.kind;
+                        if (!kind) {
+                            entry.urlUnavailable = 'unknownMediaKind';
+                        }
+                        else {
+                            entry.kind = kind;
+                            try {
+                                entry.url = yield this._mintResultUrl({
+                                    projectId: snapshot.id,
+                                    jobId: id,
+                                    kind,
+                                    audioContentType: result === null || result === void 0 ? void 0 : result.contentType
+                                });
+                            }
+                            catch (error) {
+                                this.client.logger.error(`Failed to sign a download URL for ${snapshot.id}/${id}`);
+                                this.client.logger.error(error);
+                                entry.urlUnavailable = 'downloadUrlFailed';
+                            }
+                            assertSession();
+                        }
+                    }
+                }
+                jobs.push(entry);
+            }
+            return Object.assign(Object.assign(Object.assign({ id: snapshot.id, status: snapshot.status, finished: snapshot.finished }, (modelId ? { modelId } : {})), (snapshot.waitingReason !== undefined ? { waitingReason: snapshot.waitingReason } : {})), { jobs });
+        });
+    }
+    /**
+     * This account's recently completed projects that produced media, newest
+     * first, read from the durable history rather than the socket. It includes
+     * projects that finished while no client was connected, and ones the socket
+     * has stopped holding for a reconnect (it keeps a finished project for one
+     * hour). Pass a project's id to {@link getResult} for its download URLs.
+     *
+     * Reaches back at most 7 days. Needs a signed-in account.
+     *
+     * @example
+     * ```ts
+     * const recent = await sogni.projects.listRecent({ since: Date.now() - 6 * 3600_000 });
+     * for (const project of recent) {
+     *   const result = await sogni.projects.getResult(project.id);
+     * }
+     * ```
+     */
+    listRecent() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            var _a, _b, _c, _d, _e, _f, _g;
+            const assertSession = (0, requestSession_js_1.captureRequestSession)(this.client.auth);
+            const address = yield this._resolveAccountAddress();
+            assertSession();
+            if (!address) {
+                throw new Error('listRecent needs a signed-in account');
+            }
+            const now = Date.now();
+            const requestedSince = options.since instanceof Date
+                ? options.since.getTime()
+                : typeof options.since === 'number'
+                    ? options.since
+                    : now - RECENT_PROJECTS_DEFAULT_WINDOW_MS;
+            const since = Math.max(requestedSince, now - RECENT_PROJECTS_MAX_WINDOW_MS);
+            const limit = Math.min(100, Math.max(1, Math.floor((_a = options.limit) !== null && _a !== void 0 ? _a : 50)));
+            const { data } = yield this.client.rest.get('/v1/jobs/list', Object.assign({ role: 'artist', address, state: 'completed', mediaOnly: true, since,
+                limit }, (options.appSource ? { appSource: options.appSource } : {})));
+            assertSession();
+            const projects = new Map();
+            for (const job of (data === null || data === void 0 ? void 0 : data.jobs) || []) {
+                const projectId = (_b = job.parentRequest) === null || _b === void 0 ? void 0 : _b.id;
+                if (!projectId)
+                    continue;
+                let project = projects.get(projectId);
+                if (!project) {
+                    project = Object.assign(Object.assign(Object.assign(Object.assign({ id: projectId }, (((_d = (_c = job.parentRequest) === null || _c === void 0 ? void 0 : _c.model) === null || _d === void 0 ? void 0 : _d.id) ? { modelId: job.parentRequest.model.id } : {})), (((_f = (_e = job.parentRequest) === null || _e === void 0 ? void 0 : _e.model) === null || _f === void 0 ? void 0 : _f.name) ? { modelName: job.parentRequest.model.name } : {})), (((_g = job.parentRequest) === null || _g === void 0 ? void 0 : _g.appSource) ? { appSource: job.parentRequest.appSource } : {})), { jobs: [] });
+                    projects.set(projectId, project);
+                }
+                const finishedAt = typeof job.endTime === 'number' && job.endTime > 0 ? job.endTime : undefined;
+                project.jobs.push(Object.assign({ id: job.imgID || job.id, status: resultJobStatus(job), sensitiveContentWithheld: job.triggeredNSFWFilter === true && job.nsfwDetected !== true }, (finishedAt ? { finishedAt } : {})));
+                if (finishedAt && (!project.finishedAt || finishedAt > project.finishedAt)) {
+                    project.finishedAt = finishedAt;
+                }
+            }
+            return [...projects.values()].sort((a, b) => { var _a, _b; return ((_a = b.finishedAt) !== null && _a !== void 0 ? _a : 0) - ((_b = a.finishedAt) !== null && _b !== void 0 ? _b : 0); });
+        });
+    }
+    /**
+     * How {@link listRecent} learns the signed-in account's address. Set by
+     * `SogniClient`, which owns the account.
+     * @internal
+     */
+    _setAccountAddressResolver(resolve) {
+        this._accountAddress = resolve;
+    }
+    _resolveAccountAddress() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._accountAddress ? this._accountAddress() : undefined;
+        });
+    }
     /**
      * Ids of this account's projects that are currently live on the socket,
      * including ones still queued with no worker assigned.