@sogni-ai/sogni-client 4.2.0-alpha.21 → 4.2.0-alpha.23

package/src/Projects/index.ts

@@ -1223,8 +1223,26 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
   // ============================================
 
   /**
-   * Get upload URL for image
-   * @internal
+   * Request a presigned upload URL for an image asset (reference image,
+   * starting image, ControlNet image, context image, etc.). The caller
+   * uploads the image bytes via `PUT` to the returned URL before
+   * starting a project or workflow that references the asset.
+   *
+   * @param {ImageUrlParams} params - Image asset coordinates:
+   *   - imageId: Stable identifier for the asset within the job
+   *     (e.g. `"media_ref_1"`). The same id is later used to reference
+   *     the asset in workflow inputs.
+   *   - jobId: Caller-generated job/correlation id (e.g.
+   *     `"sogni-agent-1735000000-1-abcdef"`). Ties the asset to a
+   *     specific request.
+   *   - type: Asset role. Supported values include `'referenceImage'`,
+   *     `'referenceImageEnd'`, `'startingImage'`, `'cnImage'`,
+   *     `'contextImage1'`..`'contextImage16'`, `'preview'`, `'complete'`.
+   *   - contentType: Optional MIME type the caller will `PUT` (e.g.
+   *     `"image/png"`). Forwarded so the storage layer can pin the
+   *     Content-Type on the presigned URL.
+   * @return {Promise<string>} Presigned `PUT` URL the caller should
+   *   upload the image bytes to. Short-lived; use immediately.
    */
   async uploadUrl(params: ImageUrlParams) {
     const r = await this.client.rest.get<ApiResponse<{ uploadUrl: string }>>(
@@ -1235,8 +1253,13 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
   }
 
   /**
-   * Get download URL for image
-   * @internal
+   * Request a presigned download URL for a stored image asset.
+   *
+   * @param {ImageUrlParams} params - Same shape as
+   *   {@link ProjectsApi.uploadUrl}; `imageId`, `jobId`, and `type`
+   *   must match the values used at upload time.
+   * @return {Promise<string>} Presigned `GET` URL for the image.
+   *   Throws if the server response does not include a `downloadUrl`.
    */
   async downloadUrl(params: ImageUrlParams) {
     const r = await this.client.rest.get<ApiResponse<{ downloadUrl: string }>>(
@@ -1250,8 +1273,21 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
   }
 
   /**
-   * Get upload URL for media (video/audio)
-   * @internal
+   * Request a presigned upload URL for an audio or video asset
+   * (reference audio, reference video, finished media artifacts, etc.).
+   * The caller uploads the media bytes via `PUT` to the returned URL
+   * before starting a project or workflow that references the asset.
+   *
+   * @param {MediaUrlParams} params - Media asset coordinates:
+   *   - id: Stable identifier for the asset within the job
+   *     (e.g. `"media_ref_1"`). Optional for some asset roles.
+   *   - jobId: Caller-generated job/correlation id.
+   *   - type: Asset role. Supported values are `'referenceAudio'`,
+   *     `'referenceVideo'`, `'preview'`, `'complete'`.
+   *   - contentType: Optional MIME type the caller will `PUT`
+   *     (e.g. `"audio/mp4"` or `"video/mp4"`).
+   * @return {Promise<string>} Presigned `PUT` URL the caller should
+   *   upload the media bytes to.
    */
   async mediaUploadUrl(params: MediaUrlParams) {
     const r = await this.client.rest.get<ApiResponse<{ uploadUrl: string }>>(
@@ -1262,8 +1298,13 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
   }
 
   /**
-   * Get download URL for media (video/audio)
-   * @internal
+   * Request a presigned download URL for a stored audio or video asset.
+   *
+   * @param {MediaUrlParams} params - Same shape as
+   *   {@link ProjectsApi.mediaUploadUrl}; `id`, `jobId`, and `type`
+   *   must match the values used at upload time.
+   * @return {Promise<string>} Presigned `GET` URL for the media.
+   *   Throws if the server response does not include a `downloadUrl`.
    */
   async mediaDownloadUrl(params: MediaUrlParams) {
     const r = await this.client.rest.get<ApiResponse<{ downloadUrl: string }>>(

package/src/index.ts

@@ -53,6 +53,11 @@ import {
   ChatCompletionResult,
   ChatJobStateEvent,
   ChatResponseFormat,
+  ChatRunEvent,
+  ChatRunRecord,
+  ChatRunStatus,
+  StartChatRunParams,
+  StreamChatRunEventsOptions,
   ContentPart,
   HostedChatCompletionParams,
   HostedChatCompletionResult,
@@ -85,7 +90,6 @@ import CreativeWorkflowsApi, { parseCreativeWorkflowSseChunk } from './CreativeW
 import {
   CreativeWorkflowArtifact,
   CreativeWorkflowEvent,
-  CreativeWorkflowKind,
   CreativeWorkflowRecord,
   CreativeWorkflowSseEvent,
   CreativeWorkflowStatus,
@@ -93,10 +97,9 @@ import {
   ListCreativeWorkflowOptions,
   StartCreativeWorkflowOptions,
   StartCreativeWorkflowParams,
-  StartHostedToolSequenceWorkflowDependency,
-  StartHostedToolSequenceWorkflowInput,
-  StartHostedToolSequenceWorkflowStep,
-  StartImageToVideoWorkflowInput,
+  StartCreativeWorkflowDependency,
+  StartCreativeWorkflowInput,
+  StartCreativeWorkflowStep,
   StreamCreativeWorkflowEventsOptions
 } from './CreativeWorkflows/types';
 // Stats API
@@ -123,7 +126,12 @@ export type {
   ChatJobStateEvent,
   ChatMessage,
   ChatResponseFormat,
+  ChatRunEvent,
+  ChatRunRecord,
+  ChatRunStatus,
   ChatTokenUsage,
+  StartChatRunParams,
+  StreamChatRunEventsOptions,
   ContentPart,
   HostedChatCompletionChoice,
   HostedChatCompletionMessage,
@@ -132,7 +140,6 @@ export type {
   HostedCreativeWorkflowReference,
   CreativeWorkflowArtifact,
   CreativeWorkflowEvent,
-  CreativeWorkflowKind,
   CreativeWorkflowRecord,
   CreativeWorkflowSseEvent,
   CreativeWorkflowStatus,
@@ -158,10 +165,9 @@ export type {
   CreativeWorkflowHostedToolName,
   StartCreativeWorkflowOptions,
   StartCreativeWorkflowParams,
-  StartHostedToolSequenceWorkflowDependency,
-  StartHostedToolSequenceWorkflowInput,
-  StartHostedToolSequenceWorkflowStep,
-  StartImageToVideoWorkflowInput,
+  StartCreativeWorkflowDependency,
+  StartCreativeWorkflowInput,
+  StartCreativeWorkflowStep,
   StreamCreativeWorkflowEventsOptions,
   SupernetType,
   TokenType,
@@ -292,8 +298,23 @@ export class SogniClient {
   account: AccountApi;
   projects: ProjectsApi;
   stats: StatsApi;
+  /**
+   * Chat surfaces.
+   * - `chat.completions.create` — socket-native chat completion.
+   * - `chat.hosted.create` — hosted REST chat completion (synchronous).
+   * - `chat.runs.{create, get, cancel, streamEvents}` — durable hosted
+   *   chat runs that survive client disconnect, browser close, network
+   *   drop, and API worker restart. See `/v1/chat/runs` REST surface.
+   * - `chat.tools.execute*` — execute Sogni platform tools surfaced by
+   *   the chat completion (image / video / music generation).
+   */
   chat: ChatApi;
-  creativeWorkflows: CreativeWorkflowsApi;
+  /**
+   * Durable creative workflows (`/v1/creative-agent/workflows`). Submit
+   * an explicit step sequence and follow its progress without keeping
+   * the client connected.
+   */
+  workflows: CreativeWorkflowsApi;
 
   apiClient: ApiClient;
 
@@ -302,7 +323,7 @@ export class SogniClient {
     this.projects = new ProjectsApi(config);
     this.stats = new StatsApi(config);
     this.chat = new ChatApi(config, this.projects);
-    this.creativeWorkflows = new CreativeWorkflowsApi(config);
+    this.workflows = new CreativeWorkflowsApi(config);
 
     this.apiClient = config.client;
   }

package/src/lib/Cache.ts

@@ -10,7 +10,14 @@ export default class Cache<V = any> {
 
   constructor(defaultTTL: number) {
     this.ttl = defaultTTL;
-    setInterval(() => this.cleanup(), 10000);
+    const timer = setInterval(() => this.cleanup(), 10000) as unknown as {
+      unref?: () => void;
+    };
+    // Node timers have unref() so a module-level Cache doesn't keep one-shot
+    // scripts alive. Browser timers return numbers and don't expose unref.
+    if (typeof timer.unref === 'function') {
+      timer.unref();
+    }
   }
 
   write(key: string, value: V, ttl?: number) {

package/src/lib/mediaValidation.ts

@@ -8,6 +8,8 @@ export interface ImageDimensions {
 export interface InlineMediaValidationOptions {
   maxBytes?: number;
   maxImageLongestSide?: number;
+  remoteFetchTimeoutMs?: number;
+  signal?: AbortSignal;
 }
 
 export interface ParsedInlineMediaData {
@@ -320,6 +322,109 @@ function validateMagicBytes(
   return undefined;
 }
 
+function mimeTypeForDetectedFormat(mediaType: MediaType, bytes: Uint8Array): string {
+  if (mediaType === 'image') {
+    const format = detectImageFormat(bytes);
+    if (format === 'png') return 'image/png';
+    if (format === 'jpeg') return 'image/jpeg';
+  } else if (mediaType === 'audio') {
+    const format = detectAudioFormat(bytes);
+    if (format === 'wav') return 'audio/wav';
+    if (format === 'mpeg') return 'audio/mpeg';
+    if (format === 'mp4') return 'audio/mp4';
+  } else {
+    const format = detectVideoFormat(bytes);
+    if (format === 'quicktime') return 'video/quicktime';
+    if (format === 'mp4') return 'video/mp4';
+  }
+  throw new Error(
+    `Remote ${mediaType} input is not a supported format. Allowed types: ${getAllowedMimeTypes(mediaType).join(', ')}`
+  );
+}
+
+function normalizeResponseMimeType(
+  mediaType: MediaType,
+  contentType: string | null,
+  bytes: Uint8Array
+): string {
+  const mimeType = contentType?.split(';')[0]?.trim().toLowerCase() || '';
+  if (getAllowedMimeTypes(mediaType).includes(mimeType)) return mimeType;
+  return mimeTypeForDetectedFormat(mediaType, bytes);
+}
+
+function throwMediaByteLimit(mediaType: MediaType, maxBytes: number): never {
+  throw new Error(`${mediaType} input exceeds ${Math.round(maxBytes / (1024 * 1024))}MB limit`);
+}
+
+async function readResponseBytes(
+  response: Response,
+  mediaType: MediaType,
+  maxBytes: number | undefined
+): Promise<Uint8Array> {
+  if (!response.body) {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (maxBytes !== undefined && bytes.length > maxBytes) {
+      throwMediaByteLimit(mediaType, maxBytes);
+    }
+    return bytes;
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+
+      totalBytes += value.byteLength;
+      if (maxBytes !== undefined && totalBytes > maxBytes) {
+        try {
+          await reader.cancel();
+        } catch {
+          // Preserve the size-limit error below.
+        }
+        throwMediaByteLimit(mediaType, maxBytes);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+const DEFAULT_REMOTE_MEDIA_FETCH_TIMEOUT_MS = 20_000;
+
+function trustedRemoteMediaUrl(value: string): URL | null {
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol !== 'https:') return null;
+    if (url.username || url.password) return null;
+    const host = url.hostname.toLowerCase();
+    const trusted =
+      host === 'cdn.sogni.ai' ||
+      host.endsWith('.sogni.ai') ||
+      host === 'complete-images-production.s3.amazonaws.com' ||
+      /^[a-z0-9.-]+\.s3\.amazonaws\.com$/i.test(host) ||
+      /^[a-z0-9.-]+\.s3\.[a-z0-9-]+\.amazonaws\.com$/i.test(host) ||
+      /^s3\.[a-z0-9-]+\.amazonaws\.com$/i.test(host) ||
+      host.endsWith('.cloudfront.net');
+    return trusted ? url : null;
+  } catch {
+    return null;
+  }
+}
+
 function validateImageDimensions(dimensions: ImageDimensions, maxLongestSide: number): void {
   if (Math.max(dimensions.width, dimensions.height) > maxLongestSide) {
     throw new Error(
@@ -365,3 +470,53 @@ export function parseInlineMediaDataUri(
     imageDimensions
   };
 }
+
+export async function mediaInputToInlineDataUri(
+  input: string,
+  mediaType: MediaType,
+  options: InlineMediaValidationOptions = {}
+): Promise<string> {
+  const trimmed = input.trim();
+  const remoteUrl = trustedRemoteMediaUrl(trimmed);
+  if (!remoteUrl) {
+    parseInlineMediaDataUri(trimmed, mediaType, options);
+    return trimmed;
+  }
+
+  const controller = new AbortController();
+  const timeoutMs = options.remoteFetchTimeoutMs ?? DEFAULT_REMOTE_MEDIA_FETCH_TIMEOUT_MS;
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  const abortFromParent = () => controller.abort();
+  options.signal?.addEventListener('abort', abortFromParent, { once: true });
+  try {
+    if (options.signal?.aborted) controller.abort();
+    const response = await fetch(remoteUrl.toString(), {
+      signal: controller.signal,
+      redirect: 'error'
+    });
+    if (!response.ok) {
+      throw new Error(`Remote ${mediaType} input fetch failed with HTTP ${response.status}`);
+    }
+    const contentLength = Number(response.headers.get('content-length') || '');
+    if (
+      options.maxBytes !== undefined &&
+      Number.isFinite(contentLength) &&
+      contentLength > options.maxBytes
+    ) {
+      throwMediaByteLimit(mediaType, options.maxBytes);
+    }
+
+    const bytes = await readResponseBytes(response, mediaType, options.maxBytes);
+    const mimeType = normalizeResponseMimeType(
+      mediaType,
+      response.headers.get('content-type'),
+      bytes
+    );
+    const dataUri = `data:${mimeType};base64,${encodeBase64(bytes)}`;
+    parseInlineMediaDataUri(dataUri, mediaType, options);
+    return dataUri;
+  } finally {
+    clearTimeout(timeoutId);
+    options.signal?.removeEventListener('abort', abortFromParent);
+  }
+}