@acedatacloud/sdk 2026.718.1 → 2026.727.0

package/src/runtime/tasks.ts

@@ -1,4 +1,15 @@
-/** Task polling abstraction. */
+/**
+ * Task polling for long-running operations.
+ *
+ * A generation call always returns a handle, never sometimes a handle and
+ * sometimes a plain object — the caller decides whether to wait. When the server
+ * answers synchronously (some endpoints do for fast or cached results) the
+ * handle is born already complete, so `wait()` returns immediately rather than
+ * polling for something that has already arrived.
+ *
+ * Kept behaviourally identical to the Python and Go implementations; a
+ * divergence here is a cross-language bug that only shows up in production.
+ */
 
 import { Transport } from './transport';
 
@@ -7,17 +18,135 @@ export interface TaskHandleOptions {
   maxWait?: number;
 }
 
-function taskStatus(state: Record<string, unknown>): 'succeeded' | 'failed' | '' {
+const DONE = new Set(['succeed', 'succeeded', 'success', 'completed', 'complete', 'finished']);
+const FAILED = new Set(['failed', 'failure', 'error', 'cancelled', 'canceled', 'rejected']);
+
+function statusWords(node: unknown, depth = 0): string[] {
+  if (depth > 6) return [];
+  const out: string[] = [];
+  if (Array.isArray(node)) {
+    for (const item of node) out.push(...statusWords(item, depth + 1));
+  } else if (node && typeof node === 'object') {
+    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+      if ((key === 'state' || key === 'status') && typeof value === 'string') {
+        out.push(value.toLowerCase());
+      } else {
+        out.push(...statusWords(value, depth + 1));
+      }
+    }
+  }
+  return out;
+}
+
+function collectUrls(node: unknown, out: string[], depth = 0): void {
+  if (depth > 6) return;
+  if (Array.isArray(node)) {
+    for (const item of node) collectUrls(item, out, depth + 1);
+  } else if (node && typeof node === 'object') {
+    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+      const looksLikeUrl = key.endsWith('_url') || key === 'url' || key.endsWith('_urls');
+      if (typeof value === 'string' && value.startsWith('http') && looksLikeUrl) {
+        out.push(value);
+      } else {
+        collectUrls(value, out, depth + 1);
+      }
+    }
+  }
+}
+
+/**
+ * Every artifact URL in a task response, outermost first.
+ *
+ * Where the artifact lives is not derivable from the OpenAPI spec — `response`
+ * is typed as a bare object and the key differs per service (`video_url`,
+ * `image_url`, `data[].image_url`). Rather than keep a per-service table that
+ * goes stale, collect anything URL-shaped.
+ */
+export function artifactUrls(state: Record<string, unknown> | null): string[] {
+  if (!state) return [];
+  const found: string[] = [];
+  collectUrls(state.response ?? state, found);
+  return [...new Set(found)];
+}
+
+/** Percent complete when the service reports it, else null. */
+export function taskProgress(state: Record<string, unknown> | null): number | null {
+  if (!state) return null;
+  for (const value of findKeys(state.response ?? state, ['progress', 'percent', 'percentage'])) {
+    if (typeof value === 'boolean') continue;
+    if (typeof value === 'number') {
+      const pct = value > 0 && value <= 1 ? Math.round(value * 100) : Math.round(value);
+      return Math.max(0, Math.min(100, pct));
+    }
+    if (typeof value === 'string') {
+      const parsed = Number.parseFloat(value.trim().replace(/%$/, ''));
+      if (!Number.isNaN(parsed)) return Math.max(0, Math.min(100, Math.round(parsed)));
+    }
+  }
+  return null;
+}
+
+function* findKeys(node: unknown, names: string[], depth = 0): Generator<unknown> {
+  if (depth > 6) return;
+  if (Array.isArray(node)) {
+    for (const item of node) yield* findKeys(item, names, depth + 1);
+  } else if (node && typeof node === 'object') {
+    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+      if (names.includes(key)) yield value;
+      else yield* findKeys(value, names, depth + 1);
+    }
+  }
+}
+
+/** The upstream's own words for why a task failed. */
+export function failureReason(state: Record<string, unknown> | null): string {
+  if (!state) return 'Task failed.';
   const response = (state.response ?? state) as Record<string, unknown>;
-  if (response.status === 'succeeded' || response.status === 'failed') return response.status;
-  if (response.status !== undefined && response.status !== null) return '';
+  const error = response.error;
+  if (error && typeof error === 'object') {
+    const message = (error as Record<string, unknown>).message ?? (error as Record<string, unknown>).detail;
+    if (typeof message === 'string' && message) return message;
+  } else if (typeof error === 'string' && error) {
+    return error;
+  }
+  for (const key of ['message', 'failure_reason', 'fail_reason']) {
+    const value = response[key];
+    if (typeof value === 'string' && value) return value;
+  }
+  return 'Task failed.';
+}
+
+/**
+ * Reduce a poll response to succeeded | failed | '' (still running).
+ *
+ * Services report completion inconsistently. A status word is the strongest
+ * signal and outranks the `success` flag, since a response can carry
+ * `success: false` for a retryable hiccup while the task is still running.
+ * This normaliser is deliberately broad; narrowing it silently hangs whichever
+ * service it drops.
+ */
+export function taskStatus(state: Record<string, unknown>): 'succeeded' | 'failed' | '' {
+  const response = (state.response ?? state) as Record<string, unknown> | null;
+  if (!response || typeof response !== 'object') return '';
+
+  const words = statusWords(response);
+  if (words.some((w) => FAILED.has(w))) return 'failed';
+  if (words.some((w) => DONE.has(w))) {
+    // A terminal word with no artifact means the job ended without output.
+    return artifactUrls(state).length > 0 ? 'succeeded' : 'failed';
+  }
+  if (words.length > 0) return '';
+
   const finished =
     (response.finished_at !== undefined && response.finished_at !== null) ||
     (state.finished_at !== undefined && state.finished_at !== null);
-  if (!finished) return '';
-  if (response.success === true) return 'succeeded';
-  if (response.success === false) return 'failed';
-  return '';
+  if (finished) {
+    if (response.success === true) return 'succeeded';
+    if (response.success === false) return 'failed';
+    if (artifactUrls(state).length > 0) return 'succeeded';
+  }
+
+  return artifactUrls(state).length > 0 ? 'succeeded' : '';
 }
 
 export class TaskHandle {
@@ -26,10 +155,33 @@ export class TaskHandle {
   private transport: Transport;
   private _result: Record<string, unknown> | null = null;
 
-  constructor(taskId: string, pollEndpoint: string, transport: Transport) {
+  constructor(
+    taskId: string,
+    pollEndpoint: string,
+    transport: Transport,
+    submitted?: Record<string, unknown>,
+  ) {
     this.id = taskId;
     this.pollEndpoint = pollEndpoint;
     this.transport = transport;
+    // A submission that already carried the artifact is a finished task. The
+    // caller should not have to detect that and skip wait() themselves.
+    if (submitted && artifactUrls({ response: submitted }).length > 0) {
+      this._result = { response: submitted };
+    }
+  }
+
+  get done(): boolean {
+    return this._result !== null;
+  }
+
+  /** Artifact URLs, once completed. */
+  urls(): string[] {
+    return artifactUrls(this._result);
+  }
+
+  progress(): number | null {
+    return taskProgress(this._result);
   }
 
   async get(): Promise<Record<string, unknown>> {
@@ -39,12 +191,14 @@ export class TaskHandle {
   }
 
   async isCompleted(): Promise<boolean> {
-    const state = await this.get();
-    const status = taskStatus(state);
+    if (this.done) return true;
+    const status = taskStatus(await this.get());
     return status === 'succeeded' || status === 'failed';
   }
 
   async wait(opts: TaskHandleOptions = {}): Promise<Record<string, unknown>> {
+    if (this._result !== null) return this._result;
+
     const pollInterval = opts.pollInterval ?? 3000;
     const maxWait = opts.maxWait ?? 600_000;
     const start = Date.now();

package/src/runtime/transport.ts

@@ -17,6 +17,24 @@ import type {
   PaymentRequiredBody,
 } from './payment';
 
+function parsePaymentRequired(resp: Response, text: string): PaymentRequiredBody {
+  const encoded = resp.headers.get('PAYMENT-REQUIRED');
+  if (encoded) {
+    try {
+      return JSON.parse(atob(encoded)) as PaymentRequiredBody;
+    } catch {
+      throw mapError(402, {
+        error: { code: 'invalid_402', message: 'Invalid PAYMENT-REQUIRED header' },
+      });
+    }
+  }
+  try {
+    return JSON.parse(text) as PaymentRequiredBody;
+  } catch {
+    throw mapError(402, { error: { code: 'invalid_402', message: text } });
+  }
+}
+
 const ERROR_CODE_MAP: Record<string, typeof APIError> = {
   invalid_token: AuthenticationError,
   token_expired: AuthenticationError,
@@ -171,12 +189,7 @@ export class Transport {
 
         if (resp.status === 402 && this.paymentHandler && !paymentAttempted) {
           const text = await resp.text();
-          let body: unknown;
-          try {
-            body = JSON.parse(text);
-          } catch {
-            throw mapError(402, { error: { code: 'invalid_402', message: text } });
-          }
+          const body = parsePaymentRequired(resp, text);
           if (
             !body ||
             typeof body !== 'object' ||
@@ -267,12 +280,7 @@ export class Transport {
 
         if (resp.status === 402 && this.paymentHandler && !paymentAttempted) {
           const text = await resp.text();
-          let body: unknown;
-          try {
-            body = JSON.parse(text);
-          } catch {
-            throw mapError(402, { error: { code: 'invalid_402', message: text } });
-          }
+          const body = parsePaymentRequired(resp, text);
           if (
             !body ||
             typeof body !== 'object' ||