@mindstudio-ai/agent 0.1.47 → 0.1.49

package/dist/index.d.ts

@@ -656,12 +656,13 @@ interface TableConfig {
     defaults?: Record<string, unknown>;
     /**
      * Platform-managed auth columns. Set when this table is the app's auth
-     * table. Writes to email/phone columns throw; roles writes are allowed.
+     * table. Writes to email/phone/apiKey columns throw; roles writes are allowed.
      */
     managedColumns?: {
         email?: string;
         phone?: string;
         roles?: string;
+        apiKey?: string;
     };
     /**
      * Sync role changes to the platform after a successful auth table write.
@@ -956,7 +957,7 @@ declare class Table<T> {
      * @param data - Row data to insert (or update on conflict). Defaults apply.
      */
     upsert(conflictKey: (keyof Omit<T, SystemFields> & string) | (keyof Omit<T, SystemFields> & string)[], data: PushInput<T>): Mutation<T>;
-    /** @internal Throw if data includes a platform-managed email/phone column. */
+    /** @internal Throw if data includes a platform-managed read-only column. */
     private _checkManagedColumns;
     /**
      * @internal Fire role sync for rows that wrote to the roles column.
@@ -1212,12 +1213,16 @@ interface RunTaskResult<T = unknown> {
 /**
  * Client for the MindStudio direct step execution API.
  *
- * Create an instance and call typed step methods directly:
+ * Inside MindStudio apps, use the `mindstudio` singleton (auth is automatic):
+ * ```ts
+ * import { mindstudio } from '@mindstudio-ai/agent';
+ * const { imageUrl } = await mindstudio.generateImage({ prompt: "a sunset" });
+ * ```
  *
+ * For external usage with an API key:
  * ```ts
  * const agent = new MindStudioAgent({ apiKey: "your-key" });
- * const { imageUrl } = await agent.generateImage({ prompt: "a sunset", mode: "background" });
- * console.log(imageUrl);
+ * const { imageUrl } = await agent.generateImage({ prompt: "a sunset" });
  * ```
  *
  * Authentication is resolved in order:
@@ -6034,10 +6039,11 @@ interface StepMethods {
      */
     extractAudioFromVideo(step: ExtractAudioFromVideoStepInput, options?: StepExecutionOptions): Promise<StepExecutionResult<ExtractAudioFromVideoStepOutput>>;
     /**
-     * Download a file from a URL and extract its text content. Supports PDFs, plain text files, and other document formats.
+     * Download a file from a URL and extract its text content. Supports PDFs (including scanned/image-based PDFs via OCR), plain text files, and other document formats.
      *
      * @remarks
      * - Best suited for PDFs and raw text/document files. For web pages, use the scrapeUrl step instead.
+     * - Handles both text-layer PDFs and image-based/scanned PDFs (e.g. Figma/Canva exports, scanned documents). Image-based PDFs are processed with OCR automatically — there is no need to convert PDF pages to images first.
      * - Accepts a single URL, a comma-separated list of URLs, or a JSON array of URLs.
      * - Files are rehosted on the MindStudio CDN before extraction.
      * - Maximum file size is 50MB per URL.

package/dist/index.js

@@ -1493,15 +1493,16 @@ var Table = class {
   // -------------------------------------------------------------------------
   // Internal helpers
   // -------------------------------------------------------------------------
-  /** @internal Throw if data includes a platform-managed email/phone column. */
+  /** @internal Throw if data includes a platform-managed read-only column. */
   _checkManagedColumns(data) {
     const mc = this._config.managedColumns;
     if (!mc) return;
     const keys = Object.keys(data);
     for (const key of keys) {
-      if (mc.email && key === mc.email || mc.phone && key === mc.phone) {
+      if (mc.email && key === mc.email || mc.phone && key === mc.phone || mc.apiKey && key === mc.apiKey) {
+        const friendly = key === mc.email ? "email" : key === mc.phone ? "phone" : "API key";
         throw new MindStudioError(
-          `Cannot write to "${key}" \u2014 this column is managed by auth. Use the auth API to change a user's ${key === mc.email ? "email" : "phone"}.`,
+          `Cannot write to "${key}" \u2014 this column is managed by auth. Use the auth API to change a user's ${friendly}.`,
           "managed_column_write",
           400
         );
@@ -1958,8 +1959,8 @@ var stepMetadata = {
   },
   "extractText": {
     stepType: "extractText",
-    description: "Download a file from a URL and extract its text content. Supports PDFs, plain text files, and other document formats.",
-    usageNotes: "- Best suited for PDFs and raw text/document files. For web pages, use the scrapeUrl step instead.\n- Accepts a single URL, a comma-separated list of URLs, or a JSON array of URLs.\n- Files are rehosted on the MindStudio CDN before extraction.\n- Maximum file size is 50MB per URL.",
+    description: "Download a file from a URL and extract its text content. Supports PDFs (including scanned/image-based PDFs via OCR), plain text files, and other document formats.",
+    usageNotes: "- Best suited for PDFs and raw text/document files. For web pages, use the scrapeUrl step instead.\n- Handles both text-layer PDFs and image-based/scanned PDFs (e.g. Figma/Canva exports, scanned documents). Image-based PDFs are processed with OCR automatically \u2014 there is no need to convert PDF pages to images first.\n- Accepts a single URL, a comma-separated list of URLs, or a JSON array of URLs.\n- Files are rehosted on the MindStudio CDN before extraction.\n- Maximum file size is 50MB per URL.",
     inputSchema: { "type": "object", "properties": { "url": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] } }, "required": ["url"] },
     outputSchema: { "type": "object", "properties": { "text": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] } }, "required": ["text"] }
   },
@@ -3672,48 +3673,80 @@ var MindStudioAgent = class {
       );
     }
     const threadId = options?.threadId ?? (this._reuseThreadId && !getRequestContext() ? this._threadId : void 0);
-    const { data, headers } = await request(this._httpConfig, "POST", `/steps/${stepType}/execute`, {
+    const { data: asyncData, headers } = await request(this._currentHttpConfig, "POST", `/steps/${stepType}/execute-async`, {
       step,
       ...options?.appId != null && { appId: options.appId },
       ...threadId != null && { threadId },
       ...this._currentStreamId != null && { streamId: this._currentStreamId }
     });
-    let output;
-    if (data.output != null) {
-      output = data.output;
-    } else if (data.outputUrl) {
-      const res = await fetch(data.outputUrl);
+    const remaining = headers.get("x-ratelimit-remaining");
+    const returnedThreadId = asyncData.threadId ?? "";
+    if (this._reuseThreadId && returnedThreadId && !getRequestContext()) {
+      this._threadId = returnedThreadId;
+    }
+    if (!this._appId && asyncData.appId && !getRequestContext()) {
+      this._appId = asyncData.appId;
+    }
+    const pollUrl = `${this._currentHttpConfig.baseUrl}/developer/v2/steps/${stepType}/execute-async/poll/${asyncData.executionToken}`;
+    let pollDelay = 100;
+    while (true) {
+      await sleep3(pollDelay);
+      pollDelay = Math.min(pollDelay * 2, 5e3);
+      const res = await fetch(pollUrl, {
+        headers: { "User-Agent": "@mindstudio-ai/agent" }
+      });
+      if (res.status === 502 || res.status === 503 || res.status === 504) continue;
+      if (res.status === 404) {
+        throw new MindStudioError(
+          `[${stepType}] Execution token expired.`,
+          "poll_token_expired",
+          404
+        );
+      }
       if (!res.ok) {
+        const errorBody = await res.json().catch(() => ({}));
         throw new MindStudioError(
-          `Failed to fetch ${stepType} output from S3: ${res.status} ${res.statusText}`,
-          "output_fetch_error",
-          res.status
+          errorBody.message ?? errorBody.error ?? `[${stepType}] Poll failed: ${res.status} ${res.statusText}`,
+          errorBody.code ?? "poll_error",
+          res.status,
+          errorBody
         );
       }
-      const envelope = await res.json();
-      output = envelope.value;
-    } else {
-      output = void 0;
-    }
-    const returnedThreadId = headers.get("x-mindstudio-thread-id") ?? "";
-    if (this._reuseThreadId && returnedThreadId && !getRequestContext()) {
-      this._threadId = returnedThreadId;
-    }
-    const returnedAppId = headers.get("x-mindstudio-app-id");
-    if (!this._appId && returnedAppId && !getRequestContext()) {
-      this._appId = returnedAppId;
+      const poll = await res.json();
+      if (poll.status === "pending") continue;
+      if (poll.status === "error") {
+        throw new MindStudioError(
+          `[${stepType}] ${poll.error ?? "Step execution failed."}`,
+          "step_error",
+          500
+        );
+      }
+      let output;
+      if (poll.output != null) {
+        output = poll.output;
+      } else if (poll.outputUrl) {
+        const s3Res = await fetch(poll.outputUrl);
+        if (!s3Res.ok) {
+          throw new MindStudioError(
+            `Failed to fetch ${stepType} output from S3: ${s3Res.status} ${s3Res.statusText}`,
+            "output_fetch_error",
+            s3Res.status
+          );
+        }
+        const envelope = await s3Res.json();
+        output = envelope.value;
+      } else {
+        output = void 0;
+      }
+      return {
+        ...output,
+        $appId: poll.appId ?? asyncData.appId ?? "",
+        $threadId: poll.threadId ?? returnedThreadId,
+        $rateLimitRemaining: remaining != null ? parseInt(remaining, 10) : void 0,
+        $billingCost: poll.billingCost,
+        $billingEvents: poll.billingEvents
+      };
     }
-    const remaining = headers.get("x-ratelimit-remaining");
-    const billingCost = headers.get("x-mindstudio-billing-cost");
-    const billingEvents = headers.get("x-mindstudio-billing-events");
-    return {
-      ...output,
-      $appId: headers.get("x-mindstudio-app-id") ?? "",
-      $threadId: returnedThreadId,
-      $rateLimitRemaining: remaining != null ? parseInt(remaining, 10) : void 0,
-      $billingCost: billingCost != null ? parseFloat(billingCost) : void 0,
-      $billingEvents: billingEvents != null ? JSON.parse(billingEvents) : void 0
-    };
   }
   /**
    * @internal Streaming step execution — sends `Accept: text/event-stream`