@sogni-ai/sogni-client 5.61.0 → 5.62.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [5.62.0](https://github.com/Sogni-AI/sogni-client/compare/v5.61.0...v5.62.0) (2026-10-09)
+
+
+### Features
+
+* **worlds:** hosted world builds on the SDK as worlds.builds ([531c039](https://github.com/Sogni-AI/sogni-client/commit/531c039134b65cad69bc56c442033b1c0ab9b29f))
+
 # [5.61.0](https://github.com/Sogni-AI/sogni-client/compare/v5.60.8...v5.61.0) (2026-10-06)
 
 

package/README.md

@@ -1578,6 +1578,19 @@ See `examples/workflow_creative_agent_workflows.mjs` for start/list/get/events/s
 
 ## Code Examples
 
+### Hosted World Builds (server-side)
+
+A hosted world build renders the paths, moments and collectibles a person chose for one scene of their Sogni World in the background, with the account's own key, while they are away. It starts from a signed-in session (an API key cannot author a world), pauses for the quote before anything paid, and pauses again when finished takes await review; publication stays in the World studio. The SDK exposes it through `sogni.worlds.builds`:
+
+- `sogni.worlds.builds.start({ worldId, nodeId, hotspots, look, tokenType, billingMode, idempotencyKey })` — start a build; each hotspot names the object as it appears, its kind (`path`, `moment` or `collectible`), the action, and for a path where it leads
+- `sogni.worlds.builds.get(runId)` and `.list({ worldId })` — inspect builds
+- `sogni.worlds.builds.events(runId, after)` and `.streamEvents(runId, { lastEventId })` — the event history and the SSE stream with `Last-Event-ID` replay
+- `sogni.worlds.builds.confirmCost(runId, { decision: 'confirm' | 'cancel' | 'requote' })` — answer the quote (a quote is good for ten minutes; ask for a requote after that)
+- `sogni.worlds.builds.review(runId, { taskId, decision: 'approved' | 'rejected', note })` — a verdict on a take in review; a rejection with a note sends it back for one rewrite
+- `sogni.worlds.builds.cancel(runId, reason)` — stop the build
+
+Read `run.waiting.reason` to see what the build needs: `cost_approval_required`, `review_required` or `insufficient_credit`. Each task's `generationId` (a path) or `interactionId` (a moment or collectible) is the World record to publish from the studio once approved.
+
 ### SAM 3 object selection
 
 SAM 3 (`sam3_image_segment_bf16`, SDK 5.31.0+) selects objects in an existing

package/dist/Worlds/index.d.ts

@@ -0,0 +1,43 @@
+import ApiGroup, { ApiConfig } from '../ApiGroup.js';
+import type { ConfirmWorldBuildCostParams, ListWorldBuildsOptions, ReviewWorldBuildTaskParams, StartWorldBuildParams, StreamWorldBuildEventsOptions, WorldBuildEvent, WorldBuildRecord } from './types.js';
+/**
+ * Sogni Worlds, as the platform hosts them (`/v1/world-builds`).
+ *
+ * A hosted world build runs server-side with the account's own key: the
+ * person starts it from a signed-in session, approves the quote, and approves
+ * or rejects every finished take. API-key sessions cannot start one.
+ *
+ * - `builds.start` returns the persisted run (202); the executor prices the
+ *   work and pauses with `waiting.reason: 'cost_approval_required'`.
+ * - `builds.confirmCost` answers the quote: confirm, cancel or requote.
+ * - `builds.review` records a verdict on a take in `review`; a rejection with
+ *   a note sends it back for one rewrite.
+ * - `builds.streamEvents` yields `WorldBuildEvent`s over SSE with
+ *   `Last-Event-ID` replay; `builds.events` lists them.
+ */
+declare class WorldsApi extends ApiGroup {
+    builds: {
+        start: (params: StartWorldBuildParams) => Promise<WorldBuildRecord>;
+        list: (options?: ListWorldBuildsOptions) => Promise<WorldBuildRecord[]>;
+        get: (runId: string) => Promise<WorldBuildRecord>;
+        events: (runId: string, afterSequence?: number) => Promise<WorldBuildEvent[]>;
+        streamEvents: (runId: string, options?: StreamWorldBuildEventsOptions) => AsyncIterableIterator<WorldBuildEvent>;
+        confirmCost: (runId: string, params: ConfirmWorldBuildCostParams) => Promise<WorldBuildRecord>;
+        review: (runId: string, params: ReviewWorldBuildTaskParams) => Promise<WorldBuildRecord>;
+        cancel: (runId: string, reason?: string) => Promise<WorldBuildRecord>;
+    };
+    constructor(config: ApiConfig);
+    /** An authenticated fetch bound to the current session: a session change cancels it. */
+    private buildFetch;
+    private buildJson;
+    private startBuild;
+    private listBuilds;
+    private getBuild;
+    private listBuildEvents;
+    private confirmBuildCost;
+    private reviewBuildTask;
+    private cancelBuild;
+    /** SSE events, replayed from `lastEventId` and then live until the run ends or the signal aborts. */
+    private streamBuildEvents;
+}
+export default WorldsApi;

package/dist/Worlds/index.js

@@ -0,0 +1,308 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ApiGroup_js_1 = __importDefault(require("../ApiGroup.js"));
+const apiErrorFields_js_1 = require("../lib/apiErrorFields.js");
+const getUUID_js_1 = __importDefault(require("../lib/getUUID.js"));
+const requestSession_js_1 = require("../lib/requestSession.js");
+/**
+ * Sogni Worlds, as the platform hosts them (`/v1/world-builds`).
+ *
+ * A hosted world build runs server-side with the account's own key: the
+ * person starts it from a signed-in session, approves the quote, and approves
+ * or rejects every finished take. API-key sessions cannot start one.
+ *
+ * - `builds.start` returns the persisted run (202); the executor prices the
+ *   work and pauses with `waiting.reason: 'cost_approval_required'`.
+ * - `builds.confirmCost` answers the quote: confirm, cancel or requote.
+ * - `builds.review` records a verdict on a take in `review`; a rejection with
+ *   a note sends it back for one rewrite.
+ * - `builds.streamEvents` yields `WorldBuildEvent`s over SSE with
+ *   `Last-Event-ID` replay; `builds.events` lists them.
+ */
+class WorldsApi extends ApiGroup_js_1.default {
+    constructor(config) {
+        super(config);
+        this.builds = {
+            start: this.startBuild.bind(this),
+            list: this.listBuilds.bind(this),
+            get: this.getBuild.bind(this),
+            events: this.listBuildEvents.bind(this),
+            streamEvents: this.streamBuildEvents.bind(this),
+            confirmCost: this.confirmBuildCost.bind(this),
+            review: this.reviewBuildTask.bind(this),
+            cancel: this.cancelBuild.bind(this)
+        };
+    }
+    /** An authenticated fetch bound to the current session: a session change cancels it. */
+    buildFetch(path_1) {
+        return __awaiter(this, arguments, void 0, function* (path, options = {}) {
+            var _a, _b, _c, _d, _e, _f;
+            const assertSession = (0, requestSession_js_1.captureRequestSession)(this.client.auth);
+            const url = new URL(path, this.client.rest.baseUrl).toString();
+            const controller = new AbortController();
+            const cancelChangedSession = () => {
+                try {
+                    assertSession();
+                }
+                catch (error) {
+                    controller.abort(error);
+                }
+            };
+            const cancelRequested = () => { var _a; return controller.abort((_a = options.signal) === null || _a === void 0 ? void 0 : _a.reason); };
+            const offAuth = (_a = this.client.auth) === null || _a === void 0 ? void 0 : _a.on('updated', cancelChangedSession);
+            const offSession = (_b = this.client.auth) === null || _b === void 0 ? void 0 : _b.on('sessionChanged', cancelChangedSession);
+            if ((_c = options.signal) === null || _c === void 0 ? void 0 : _c.aborted)
+                cancelRequested();
+            else
+                (_d = options.signal) === null || _d === void 0 ? void 0 : _d.addEventListener('abort', cancelRequested, { once: true });
+            try {
+                const authenticated = yield this.client.auth.authenticateRequest(options);
+                assertSession();
+                const response = yield fetch(url, Object.assign(Object.assign({}, authenticated), { signal: controller.signal }));
+                try {
+                    assertSession();
+                }
+                catch (error) {
+                    void ((_e = response.body) === null || _e === void 0 ? void 0 : _e.cancel().catch(() => undefined));
+                    throw error;
+                }
+                return response;
+            }
+            finally {
+                offAuth === null || offAuth === void 0 ? void 0 : offAuth();
+                offSession === null || offSession === void 0 ? void 0 : offSession();
+                (_f = options.signal) === null || _f === void 0 ? void 0 : _f.removeEventListener('abort', cancelRequested);
+            }
+        });
+    }
+    buildJson(path_1) {
+        return __awaiter(this, arguments, void 0, function* (path, options = {}) {
+            var _a;
+            const assertSession = (0, requestSession_js_1.captureRequestSession)(this.client.auth);
+            const response = yield this.buildFetch(path, options);
+            if (!response.ok) {
+                const text = yield response.text();
+                assertSession();
+                let payload;
+                try {
+                    payload = text ? JSON.parse(text) : undefined;
+                }
+                catch (_b) {
+                    payload = { message: text };
+                }
+                const message = (payload && typeof payload.message === 'string' && payload.message) ||
+                    response.statusText ||
+                    `World build request failed with status ${response.status}`;
+                // Same contract as the chat run surface: the server's message, its
+                // status, its wait in seconds and any structured context it attached.
+                const err = new Error(message);
+                err.status = response.status;
+                const extras = (0, apiErrorFields_js_1.apiErrorExtras)(payload);
+                const retryAfter = (_a = extras.retryAfter) !== null && _a !== void 0 ? _a : (0, apiErrorFields_js_1.parseRetryAfterHeader)(response.headers.get('retry-after'));
+                if (retryAfter !== undefined)
+                    err.retryAfter = retryAfter;
+                if (extras.details)
+                    err.details = extras.details;
+                throw err;
+            }
+            const body = (yield response.json());
+            assertSession();
+            return body;
+        });
+    }
+    startBuild(params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const appSource = this.client.appSource;
+            const body = Object.assign(Object.assign(Object.assign(Object.assign({ worldId: params.worldId, nodeId: params.nodeId, hotspots: params.hotspots }, (params.look ? { look: params.look } : {})), (params.audience ? { audience: params.audience } : {})), (params.tokenType ? { tokenType: params.tokenType } : {})), (params.billingMode ? { billingMode: params.billingMode } : {}));
+            const headers = Object.assign({ 'Content-Type': 'application/json' }, this.attributionHeaders(appSource, undefined, (0, getUUID_js_1.default)()));
+            if (params.idempotencyKey)
+                headers['Idempotency-Key'] = params.idempotencyKey;
+            const response = yield this.buildJson('/v1/world-builds', {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body)
+            });
+            return response.data.run;
+        });
+    }
+    listBuilds() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            const query = new URLSearchParams();
+            if (options.worldId)
+                query.set('worldId', options.worldId);
+            if (options.limit !== undefined)
+                query.set('limit', String(options.limit));
+            const suffix = query.size ? `?${query.toString()}` : '';
+            const response = yield this.buildJson(`/v1/world-builds${suffix}`);
+            return response.data.runs;
+        });
+    }
+    getBuild(runId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.buildJson(`/v1/world-builds/${encodeURIComponent(runId)}`);
+            return response.data.run;
+        });
+    }
+    listBuildEvents(runId, afterSequence) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const suffix = afterSequence !== undefined ? `?after=${encodeURIComponent(String(afterSequence))}` : '';
+            const response = yield this.buildJson(`/v1/world-builds/${encodeURIComponent(runId)}/events${suffix}`);
+            return response.data.events;
+        });
+    }
+    confirmBuildCost(runId, params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.buildJson(`/v1/world-builds/${encodeURIComponent(runId)}/confirm-cost`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ decision: params.decision }) });
+            return response.data.run;
+        });
+    }
+    reviewBuildTask(runId, params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.buildJson(`/v1/world-builds/${encodeURIComponent(runId)}/review`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(Object.assign({ taskId: params.taskId, decision: params.decision }, (params.note ? { note: params.note } : {})))
+            });
+            return response.data.run;
+        });
+    }
+    cancelBuild(runId, reason) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.buildJson(`/v1/world-builds/${encodeURIComponent(runId)}/cancel`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(reason ? { reason } : {}) });
+            return response.data.run;
+        });
+    }
+    /** SSE events, replayed from `lastEventId` and then live until the run ends or the signal aborts. */
+    streamBuildEvents(runId_1) {
+        return __asyncGenerator(this, arguments, function* streamBuildEvents_1(runId, options = {}) {
+            var _a, _b, _c, _d;
+            const checkSession = (0, requestSession_js_1.captureRequestSession)(this.client.auth);
+            const assertSession = () => {
+                var _a, _b;
+                checkSession();
+                if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+                    throw (_b = options.signal.reason) !== null && _b !== void 0 ? _b : new DOMException('The request was aborted', 'AbortError');
+                }
+            };
+            const headers = { Accept: 'text/event-stream' };
+            if (options.lastEventId !== undefined && Number.isFinite(options.lastEventId)) {
+                headers['Last-Event-ID'] = String(options.lastEventId);
+            }
+            const response = yield __await(this.buildFetch(`/v1/world-builds/${encodeURIComponent(runId)}/events/stream`, {
+                headers,
+                signal: options.signal
+            }));
+            if (!response.ok || !response.body) {
+                throw new Error(`World build event stream failed with status ${response.status}`);
+            }
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            const cancelChangedSession = () => {
+                try {
+                    assertSession();
+                }
+                catch (_a) {
+                    void reader.cancel().catch(() => undefined);
+                }
+            };
+            const offAuth = (_a = this.client.auth) === null || _a === void 0 ? void 0 : _a.on('updated', cancelChangedSession);
+            const offSession = (_b = this.client.auth) === null || _b === void 0 ? void 0 : _b.on('sessionChanged', cancelChangedSession);
+            (_c = options.signal) === null || _c === void 0 ? void 0 : _c.addEventListener('abort', cancelChangedSession, { once: true });
+            const findFrameBoundary = (source) => {
+                const lf = source.indexOf('\n\n');
+                const crlf = source.indexOf('\r\n\r\n');
+                if (lf === -1 && crlf === -1)
+                    return null;
+                if (lf === -1)
+                    return { index: crlf, length: 4 };
+                if (crlf === -1 || lf < crlf)
+                    return { index: lf, length: 2 };
+                return { index: crlf, length: 4 };
+            };
+            const parseFrame = (frame) => {
+                if (!frame.trim() || frame.startsWith(':'))
+                    return null;
+                let eventName = 'message';
+                let data = '';
+                for (const rawLine of frame.split(/\r?\n/)) {
+                    if (rawLine.startsWith('event:'))
+                        eventName = rawLine.slice(6).trim();
+                    else if (rawLine.startsWith('data:'))
+                        data += (data ? '\n' : '') + rawLine.slice(5).trim();
+                }
+                // run_status frames carry the run's status snapshot, not an event; `get` reads the same.
+                if (eventName === 'run_status' || !data)
+                    return null;
+                try {
+                    return JSON.parse(data);
+                }
+                catch (_a) {
+                    return null;
+                }
+            };
+            try {
+                assertSession();
+                while (true) {
+                    const { value, done } = yield __await(reader.read());
+                    assertSession();
+                    if (done) {
+                        const remaining = buffer.trim();
+                        if (remaining) {
+                            const parsed = parseFrame(remaining);
+                            if (parsed)
+                                yield yield __await(parsed);
+                        }
+                        return yield __await(void 0);
+                    }
+                    buffer += decoder.decode(value, { stream: true });
+                    let boundary = findFrameBoundary(buffer);
+                    while (boundary !== null) {
+                        const frame = buffer.slice(0, boundary.index);
+                        buffer = buffer.slice(boundary.index + boundary.length);
+                        boundary = findFrameBoundary(buffer);
+                        const parsed = parseFrame(frame);
+                        if (parsed) {
+                            assertSession();
+                            yield yield __await(parsed);
+                        }
+                    }
+                }
+            }
+            finally {
+                offAuth === null || offAuth === void 0 ? void 0 : offAuth();
+                offSession === null || offSession === void 0 ? void 0 : offSession();
+                (_d = options.signal) === null || _d === void 0 ? void 0 : _d.removeEventListener('abort', cancelChangedSession);
+                yield __await(reader.cancel().catch(() => undefined));
+                reader.releaseLock();
+            }
+        });
+    }
+}
+exports.default = WorldsApi;
+//# sourceMappingURL=index.js.map

package/dist/Worlds/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/Worlds/index.ts"],"names":[],"mappings":"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"}

package/dist/Worlds/types.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Hosted world builds (`/v1/world-builds`): sogni-api builds the paths,
+ * moments and collectibles a person chose for one scene of their Sogni
+ * World, in the background, with the account's own key. The person starts
+ * it from a signed-in session, approves the quote before anything paid, and
+ * approves or rejects every finished take; publication stays theirs in the
+ * World studio. Shapes mirror sogni-api `src/interface/world-build.interface.ts`.
+ */
+export type WorldBuildStatus = 'queued' | 'running' | 'waiting_for_user' | 'completed' | 'partial_failure' | 'failed' | 'cancelled';
+export type WorldBuildWaitingReason = 'cost_approval_required' | 'review_required' | 'insufficient_credit' | 'safety_review_required';
+export interface WorldBuildWaiting {
+    reason: WorldBuildWaitingReason;
+    message: string;
+    details?: Record<string, unknown>;
+    since: string;
+}
+export type WorldBuildHotspotKind = 'path' | 'moment' | 'collectible';
+export interface WorldBuildAction {
+    verb: string;
+    subject: string;
+    intent: string;
+    tone?: string;
+}
+/** One thing to build from the scene. `taskId` is optional; the server names unnamed ones `task_<n>`. */
+export interface WorldBuildHotspotInput {
+    taskId?: string;
+    kind: WorldBuildHotspotKind;
+    /** The object as it appears in the picture, lower case with its article: "the brass lantern". */
+    object: string;
+    action: WorldBuildAction;
+    /** A path's destination title. */
+    leadsTo?: string;
+    /** Film length in seconds; one of the world's creator-plan lengths. */
+    duration?: number;
+    /** Where the person or the finder saw it, as fractions of the picture: a hint for the pointer. */
+    point?: {
+        x: number;
+        y: number;
+    };
+}
+export interface StartWorldBuildParams {
+    worldId: string;
+    nodeId: string;
+    hotspots: WorldBuildHotspotInput[];
+    /** The world's visual style, carried into every film direction. */
+    look?: string;
+    audience?: 'everyone' | 'teen';
+    tokenType?: 'spark' | 'sogni';
+    billingMode?: 'auto' | 'subscription' | 'tokens';
+    /** Replays with the same key return the same run instead of starting another. */
+    idempotencyKey?: string;
+}
+export type WorldBuildTaskStep = 'pending' | 'locating' | 'outlining' | 'reserving' | 'rendering_still' | 'directing' | 'rendering_transition' | 'rendering_moment' | 'rendering_collectible' | 'review' | 'approved' | 'rejected' | 'failed' | 'cancelled';
+export interface WorldBuildTaskSelection {
+    id: string;
+    selectionHash: string;
+    projectId: string;
+    points: Array<{
+        x: number;
+        y: number;
+        label: 'positive' | 'negative';
+    }>;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    coverage: number;
+}
+export interface WorldBuildTask {
+    taskId: string;
+    kind: WorldBuildHotspotKind;
+    status: WorldBuildTaskStep;
+    attempts: number;
+    selection?: WorldBuildTaskSelection;
+    /** The World generation behind a path; publish it through the World studio once approved. */
+    generationId?: string;
+    /** The World interaction behind a moment or collectible. */
+    interactionId?: string;
+    projects: {
+        segmentation?: string;
+        target_still?: string;
+        transition?: string;
+        interaction?: string;
+    };
+    direction?: string;
+    review?: {
+        decision: 'approved' | 'rejected';
+        note?: string;
+        at: string;
+    };
+    error?: {
+        message: string;
+        code?: string;
+        at: string;
+        step: WorldBuildTaskStep;
+    };
+    startedAt?: string;
+    finishedAt?: string;
+}
+export interface WorldBuildCostLine {
+    taskId: string;
+    kind: WorldBuildHotspotKind;
+    stages: Record<string, number>;
+    total: number;
+}
+export interface WorldBuildCostPreview {
+    tokenType: 'spark' | 'sogni';
+    billingMode: 'auto' | 'subscription' | 'tokens';
+    lines: WorldBuildCostLine[];
+    total: number;
+    coveredBySubscription: boolean;
+    issuedAt: string;
+    /** Confirm before this, or ask for a requote. */
+    validUntil: string;
+}
+export interface WorldBuildEvent {
+    sequence: number;
+    type: string;
+    at: string;
+    payload?: Record<string, unknown>;
+}
+export interface WorldBuildRecord {
+    runId: string;
+    ownerWalletAddress: string;
+    worldId: string;
+    nodeId: string;
+    status: WorldBuildStatus;
+    scope: {
+        ownerWalletAddress: string;
+        appSource: string;
+        tokenType?: 'spark' | 'sogni';
+        billingMode?: 'auto' | 'subscription' | 'tokens';
+    };
+    input: {
+        worldId: string;
+        nodeId: string;
+        look?: string;
+        audience?: 'everyone' | 'teen';
+        hotspots: Array<Required<Pick<WorldBuildHotspotInput, 'taskId'>> & WorldBuildHotspotInput>;
+        plan: Record<string, unknown>;
+    };
+    tasks: WorldBuildTask[];
+    costPreview?: WorldBuildCostPreview;
+    authorization?: {
+        acceptedTotal: number;
+        tokenType: 'spark' | 'sogni';
+        previewIssuedAt: string;
+        acceptedAt: string;
+    };
+    waiting?: WorldBuildWaiting;
+    /** Absent from list responses: a build's events are a stream, read with `events` or `streamEvents`. */
+    events?: WorldBuildEvent[];
+    failureReason?: string;
+    cancellationReason?: string;
+    timestamps: {
+        createdAt: string;
+        updatedAt: string;
+        completedAt?: string;
+    };
+}
+export interface ConfirmWorldBuildCostParams {
+    /** `confirm` starts the paid work, `cancel` ends the run, `requote` asks for a fresh price. */
+    decision: 'confirm' | 'cancel' | 'requote';
+}
+export interface ReviewWorldBuildTaskParams {
+    taskId: string;
+    decision: 'approved' | 'rejected';
+    /** What is wrong with a rejected take; the rewrite reads it. */
+    note?: string;
+}
+export interface ListWorldBuildsOptions {
+    worldId?: string;
+    limit?: number;
+}
+export interface StreamWorldBuildEventsOptions {
+    /** Last event sequence observed by the caller; replay starts after it. */
+    lastEventId?: number;
+    signal?: AbortSignal;
+}

package/dist/Worlds/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Hosted world builds (`/v1/world-builds`): sogni-api builds the paths,
+ * moments and collectibles a person chose for one scene of their Sogni
+ * World, in the background, with the account's own key. The person starts
+ * it from a signed-in session, approves the quote before anything paid, and
+ * approves or rejects every finished take; publication stays theirs in the
+ * World studio. Shapes mirror sogni-api `src/interface/world-build.interface.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/Worlds/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/Worlds/types.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}

package/dist/index.d.ts

@@ -36,6 +36,7 @@ import { CreativeWorkflowArtifact, CreativeWorkflowEvent, CreativeWorkflowRecord
 import { ForkWorkflowTemplateBody, ListWorkflowTemplatesOptions, ListWorkflowTemplatesResult, WorkflowTemplate, WorkflowTemplateAuthor, WorkflowTemplateRequestOptions, WorkflowTemplateStability, WorkflowTemplateVisibility, WorkflowTemplateVisibilityFilter } from './CreativeWorkflows/Templates/types.js';
 import StatsApi from './Stats/index.js';
 import ReplayApi from './Replay/index.js';
+import WorldsApi from './Worlds/index.js';
 import AnnouncementsApi from './Announcements/index.js';
 import { GetReplayRecordResult, ListReplayRecordsOptions, ListReplayRecordsResult, ReplayRecordSummary, ReplayRequestOptions, ReplayWriteResult, RunRecord } from './Replay/types.js';
 import ErrorData, { MODEL_CONSENT_REQUIRED_ERROR_CODE, MODEL_NOT_YET_AVAILABLE_ERROR_CODE, SUBSCRIPTION_ERROR_CODES } from './types/ErrorData.js';
@@ -171,6 +172,13 @@ export declare class SogniClient {
      * the client connected.
      */
     workflows: CreativeWorkflowsApi;
+    /**
+     * Sogni Worlds (`/v1/world-builds`). `worlds.builds` starts a hosted world
+     * build from a signed-in session, answers its quote, reviews its takes and
+     * follows it over SSE; sogni-api renders in the background with the
+     * account's own key.
+     */
+    worlds: WorldsApi;
     /**
      * Replay records (`/v1/replay/records`). Writes one RunRecord per
      * chat / harness turn and exposes list + get for the replay viewer.
@@ -219,3 +227,4 @@ export declare class SogniClient {
      */
     static createInstance(config: SogniClientConfig | RestOnlySogniClientConfig): Promise<SogniClient>;
 }
+export type { ConfirmWorldBuildCostParams, ListWorldBuildsOptions, ReviewWorldBuildTaskParams, StartWorldBuildParams, StreamWorldBuildEventsOptions, WorldBuildAction, WorldBuildCostLine, WorldBuildCostPreview, WorldBuildEvent, WorldBuildHotspotInput, WorldBuildHotspotKind, WorldBuildRecord, WorldBuildStatus, WorldBuildTask, WorldBuildTaskSelection, WorldBuildTaskStep, WorldBuildWaiting, WorldBuildWaitingReason } from './Worlds/types.js';