notte-sdk 0.0.1 → 0.0.3

package/README.md

@@ -185,6 +185,28 @@ await notte.Session().use(async (session) => {
 - `getId()` - Get agent ID
 - `isRunning()` - Check if agent is running
 
+#### Structured answers with Zod
+
+Both `agent.start()` and `agent.run()` accept a Zod schema as `response_format`.
+The SDK converts it to JSON Schema before calling the API. On `run()`, the final
+`answer` is validated against the schema and typed accordingly.
+
+```typescript
+import { z } from 'zod';
+
+const Answer = z.object({ title: z.string(), summary: z.string() });
+
+await notte.Session().use(async (session) => {
+  const agent = notte.Agent({ session, max_steps: 5 });
+  const result = await agent.run({
+    task: 'Go to notte.cc and return the page title and summary',
+    response_format: Answer,
+  });
+  // result.answer is typed as { title: string; summary: string } and validated
+  console.log(result.answer.title);
+});
+```
+
 ### Secret Vaults
 
 Manage credentials securely with enterprise-grade encryption.

package/dist/index.d.mts

@@ -574,12 +574,6 @@ type AgentResponse = {
      * Whether the agent is saved as a workflow
      */
     saved?: boolean;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the agent. None if the agent is still running
-     */
-    credit_usage?: number | null;
 };
 /**
  * AgentStatus
@@ -589,12 +583,6 @@ type AgentStatus = 'active' | 'closed';
  * AgentStatusResponse
  */
 type AgentStatusResponse = {
-    /**
-     * Replay
-     *
-     * The session replay in `.webp` format
-     */
-    replay?: Blob | File | null;
     /**
      * Agent Id
      *
@@ -629,12 +617,6 @@ type AgentStatusResponse = {
      * Whether the agent is saved as a workflow
      */
     saved?: boolean;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the agent. None if the agent is still running
-     */
-    credit_usage?: number | null;
     /**
      * Task
      *
@@ -667,18 +649,6 @@ type AgentStatusResponse = {
     steps?: Array<{
         [key: string]: unknown;
     }>;
-    /**
-     * Replay Start Offset
-     *
-     * The start offset of the replay
-     */
-    replay_start_offset: number;
-    /**
-     * Replay Stop Offset
-     *
-     * The stop offset of the replay
-     */
-    replay_stop_offset: number;
 };
 /**
  * AnythingStartRequest
@@ -950,6 +920,12 @@ type ApiSessionStartRequest = {
     extra_http_headers?: {
         [key: string]: string;
     } | null;
+    /**
+     * Vault Id
+     *
+     * The vault to use for the session
+     */
+    vault_id?: string | null;
 };
 /**
  * BaseModel
@@ -2463,6 +2439,12 @@ type GlobalScrapeRequest = {
     extra_http_headers?: {
         [key: string]: string;
     } | null;
+    /**
+     * Vault Id
+     *
+     * The vault to use for the session
+     */
+    vault_id?: string | null;
     /**
      * Selector
      *
@@ -2696,12 +2678,6 @@ type ImprovePromptResponse = {
  * LegacyAgentStatusResponse
  */
 type LegacyAgentStatusResponse = {
-    /**
-     * Replay
-     *
-     * The session replay in `.webp` format
-     */
-    replay?: Blob | File | null;
     /**
      * Agent Id
      *
@@ -2736,12 +2712,6 @@ type LegacyAgentStatusResponse = {
      * Whether the agent is saved as a workflow
      */
     saved?: boolean;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the agent. None if the agent is still running
-     */
-    credit_usage?: number | null;
     /**
      * Task
      *
@@ -2772,18 +2742,6 @@ type LegacyAgentStatusResponse = {
     steps?: Array<{
         [key: string]: unknown;
     }>;
-    /**
-     * Replay Start Offset
-     *
-     * The start offset of the replay
-     */
-    replay_start_offset: number;
-    /**
-     * Replay Stop Offset
-     *
-     * The stop offset of the replay
-     */
-    replay_stop_offset: number;
 };
 /**
  * ListCredentialsResponse
@@ -4039,12 +3997,6 @@ type SessionResponse = {
      * Error message if the operation failed to complete
      */
     error?: string | null;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the session. None
-     */
-    credit_usage?: number | null;
     /**
      * Proxies
      *
@@ -5605,12 +5557,6 @@ type SessionResponseWritable = {
      * Error message if the operation failed to complete
      */
     error?: string | null;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the session. None
-     */
-    credit_usage?: number | null;
     /**
      * Proxies
      *
@@ -8907,11 +8853,19 @@ declare class Agent {
     /**
      * Start an agent task (non-blocking) - mirrors Python start method
      */
+    start<T>(data: AgentRunRequest & {
+        response_format: z.ZodSchema<T>;
+    }): Promise<AgentResponse>;
     start(data: AgentRunRequest): Promise<AgentResponse>;
     /**
      * Run agent task (blocking) - mirrors Python run method behavior
      * This is the main method that mirrors the Python SDK's run method
      */
+    run<T>(data: AgentRunRequest & {
+        response_format: z.ZodSchema<T>;
+    }): Promise<LegacyAgentStatusResponse & {
+        answer: T | null;
+    }>;
     run(data: AgentRunRequest): Promise<LegacyAgentStatusResponse>;
     /**
      * Watch logs and wait for completion - mirrors Python watch_logs_and_wait

package/dist/index.d.ts

@@ -574,12 +574,6 @@ type AgentResponse = {
      * Whether the agent is saved as a workflow
      */
     saved?: boolean;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the agent. None if the agent is still running
-     */
-    credit_usage?: number | null;
 };
 /**
  * AgentStatus
@@ -589,12 +583,6 @@ type AgentStatus = 'active' | 'closed';
  * AgentStatusResponse
  */
 type AgentStatusResponse = {
-    /**
-     * Replay
-     *
-     * The session replay in `.webp` format
-     */
-    replay?: Blob | File | null;
     /**
      * Agent Id
      *
@@ -629,12 +617,6 @@ type AgentStatusResponse = {
      * Whether the agent is saved as a workflow
      */
     saved?: boolean;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the agent. None if the agent is still running
-     */
-    credit_usage?: number | null;
     /**
      * Task
      *
@@ -667,18 +649,6 @@ type AgentStatusResponse = {
     steps?: Array<{
         [key: string]: unknown;
     }>;
-    /**
-     * Replay Start Offset
-     *
-     * The start offset of the replay
-     */
-    replay_start_offset: number;
-    /**
-     * Replay Stop Offset
-     *
-     * The stop offset of the replay
-     */
-    replay_stop_offset: number;
 };
 /**
  * AnythingStartRequest
@@ -950,6 +920,12 @@ type ApiSessionStartRequest = {
     extra_http_headers?: {
         [key: string]: string;
     } | null;
+    /**
+     * Vault Id
+     *
+     * The vault to use for the session
+     */
+    vault_id?: string | null;
 };
 /**
  * BaseModel
@@ -2463,6 +2439,12 @@ type GlobalScrapeRequest = {
     extra_http_headers?: {
         [key: string]: string;
     } | null;
+    /**
+     * Vault Id
+     *
+     * The vault to use for the session
+     */
+    vault_id?: string | null;
     /**
      * Selector
      *
@@ -2696,12 +2678,6 @@ type ImprovePromptResponse = {
  * LegacyAgentStatusResponse
  */
 type LegacyAgentStatusResponse = {
-    /**
-     * Replay
-     *
-     * The session replay in `.webp` format
-     */
-    replay?: Blob | File | null;
     /**
      * Agent Id
      *
@@ -2736,12 +2712,6 @@ type LegacyAgentStatusResponse = {
      * Whether the agent is saved as a workflow
      */
     saved?: boolean;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the agent. None if the agent is still running
-     */
-    credit_usage?: number | null;
     /**
      * Task
      *
@@ -2772,18 +2742,6 @@ type LegacyAgentStatusResponse = {
     steps?: Array<{
         [key: string]: unknown;
     }>;
-    /**
-     * Replay Start Offset
-     *
-     * The start offset of the replay
-     */
-    replay_start_offset: number;
-    /**
-     * Replay Stop Offset
-     *
-     * The stop offset of the replay
-     */
-    replay_stop_offset: number;
 };
 /**
  * ListCredentialsResponse
@@ -4039,12 +3997,6 @@ type SessionResponse = {
      * Error message if the operation failed to complete
      */
     error?: string | null;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the session. None
-     */
-    credit_usage?: number | null;
     /**
      * Proxies
      *
@@ -5605,12 +5557,6 @@ type SessionResponseWritable = {
      * Error message if the operation failed to complete
      */
     error?: string | null;
-    /**
-     * Credit Usage
-     *
-     * Credit usage for the session. None
-     */
-    credit_usage?: number | null;
     /**
      * Proxies
      *
@@ -8907,11 +8853,19 @@ declare class Agent {
     /**
      * Start an agent task (non-blocking) - mirrors Python start method
      */
+    start<T>(data: AgentRunRequest & {
+        response_format: z.ZodSchema<T>;
+    }): Promise<AgentResponse>;
     start(data: AgentRunRequest): Promise<AgentResponse>;
     /**
      * Run agent task (blocking) - mirrors Python run method behavior
      * This is the main method that mirrors the Python SDK's run method
      */
+    run<T>(data: AgentRunRequest & {
+        response_format: z.ZodSchema<T>;
+    }): Promise<LegacyAgentStatusResponse & {
+        answer: T | null;
+    }>;
     run(data: AgentRunRequest): Promise<LegacyAgentStatusResponse>;
     /**
      * Watch logs and wait for completion - mirrors Python watch_logs_and_wait

package/dist/index.js

@@ -1690,6 +1690,16 @@ var Session = class {
 
 // src/agent.ts
 var import_ws = __toESM(require("ws"));
+var import_zod2 = require("zod");
+function prepareAgentRequest(data) {
+  const apiData = { ...data };
+  const rf = data.response_format;
+  if (rf && typeof rf.parse === "function" && typeof rf.safeParse === "function") {
+    apiData.response_format = import_zod2.z.toJSONSchema(rf);
+    return { apiData, zodSchema: rf };
+  }
+  return { apiData, zodSchema: null };
+}
 function validatePersonaOption(persona, persona_id) {
   if (persona) {
     try {
@@ -1812,9 +1822,6 @@ var Agent = class {
       throw new Error("Either session (for running a new agent) or agent_id (for accessing an existing agent) have to be provided");
     }
   }
-  /**
-   * Start an agent task (non-blocking) - mirrors Python start method
-   */
   async start(data) {
     if (this.existingAgent) {
       throw new Error("You cannot call start() on an agent instantiated from agent id");
@@ -1823,9 +1830,10 @@ var Agent = class {
       throw new Error("Agent not properly initialized with session");
     }
     try {
+      const { apiData } = prepareAgentRequest(data);
       const requestBody = {
         ...this.request,
-        ...data
+        ...apiData
       };
       const response = await agentStart({
         client: this.client.getClient(),
@@ -1840,17 +1848,28 @@ var Agent = class {
       throw new Error(`Failed to start agent: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  /**
-   * Run agent task (blocking) - mirrors Python run method behavior
-   * This is the main method that mirrors the Python SDK's run method
-   */
   async run(data) {
     if (this.existingAgent) {
       throw new Error("You cannot call run() on an agent instantiated from agent id");
     }
-    this.response = await this.start(data);
+    const { apiData, zodSchema } = prepareAgentRequest(data);
+    this.response = await this.start(apiData);
     console.log(`[Agent] ${this.agentId} started`);
-    return await this.watchLogsAndWait(true, data.updateHandler || null);
+    const result = await this.watchLogsAndWait(true, data.updateHandler || null);
+    if (zodSchema && result && result.answer !== void 0 && result.answer !== null) {
+      let candidate;
+      try {
+        candidate = typeof result.answer === "string" ? JSON.parse(result.answer) : result.answer;
+      } catch {
+        throw new Error(`Agent answer is not valid JSON and cannot be validated against the schema`);
+      }
+      try {
+        result.answer = zodSchema.parse(candidate);
+      } catch (error) {
+        throw new Error(`Agent answer schema validation failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    return result;
   }
   /**
    * Watch logs and wait for completion - mirrors Python watch_logs_and_wait
@@ -2568,7 +2587,7 @@ var NottePersona = class {
 };
 
 // src/version.ts
-var SDK_VERSION = true ? "0.0.1" : "dev";
+var SDK_VERSION = true ? "0.0.3" : "dev";
 
 // src/functions.ts
 var NotteFunction = class {
@@ -2645,7 +2664,7 @@ var NotteFunction = class {
 };
 
 // src/client.ts
-var import_zod2 = require("zod");
+var import_zod3 = require("zod");
 var NotteClient = class {
   constructor(config = {}) {
     const apiKey = config.apiKey || process.env.NOTTE_API_KEY;
@@ -2654,12 +2673,13 @@ var NotteClient = class {
       throw new Error("API key is required. Provide it via config.apiKey or set the NOTTE_API_KEY environment variable.");
     }
     this.config = {
-      baseUrl: config.baseUrl || "https://api.notte.cc",
+      baseUrl: config.baseUrl || process.env.NOTTE_API_URL || "https://api.notte.cc",
       apiKey,
       ...config
     };
     client.setConfig({
-      baseUrl: this.config.baseUrl
+      baseUrl: this.config.baseUrl,
+      redirect: "manual"
     });
     client.interceptors.request.use((request) => {
       request.headers.set("Authorization", `Bearer ${this.config.apiKey}`);
@@ -2667,6 +2687,33 @@ var NotteClient = class {
       request.headers.set("x-notte-sdk-version", SDK_VERSION);
       return request;
     });
+    client.interceptors.response.use(async (response, request, opts) => {
+      if ((response.status === 307 || response.status === 308) && response.headers.get("location")) {
+        const location = response.headers.get("location");
+        const headers = new Headers(request.headers);
+        if (new URL(location).origin !== new URL(request.url).origin) {
+          headers.delete("Authorization");
+        }
+        const headerRecord = {};
+        headers.forEach((v, k) => {
+          headerRecord[k] = v;
+        });
+        const redirected = await fetch(location, {
+          method: request.method,
+          headers: headerRecord,
+          body: opts.serializedBody ?? void 0
+        });
+        return redirected;
+      }
+      const ct = response.headers.get("content-type") ?? "";
+      if (ct.split(";")[0]?.trim() === "text/plain") {
+        const body = await response.arrayBuffer();
+        const headers = new Headers(response.headers);
+        headers.set("content-type", "application/json");
+        return new Response(body, { status: response.status, statusText: response.statusText, headers });
+      }
+      return response;
+    });
   }
   /**
    * Create a new session
@@ -2727,7 +2774,7 @@ var NotteClient = class {
       if (options.json_schema) {
         apiOptions.response_format = options.json_schema;
       } else {
-        apiOptions.response_format = import_zod2.z.toJSONSchema(options.response_format);
+        apiOptions.response_format = import_zod3.z.toJSONSchema(options.response_format);
       }
       if (!apiOptions.instructions) {
         const schemaStr = JSON.stringify(apiOptions.response_format);