notte-sdk

TypeScript SDK for Notte - Cloud-hosted browser sessions with LLM-powered web agents

The official TypeScript SDK for Notte API, providing cloud-hosted browser sessions with precise control, LLM-powered web agents for automated tasks, serverless functions, and secure credential management.

Features

• 🌐 Cloud Browser Sessions - Access remote browsers with full control
• 🤖 LLM-Powered Agents - Intelligent web automation with natural language
• 🔒 Secret Vaults - Enterprise-grade credential management with end-to-end encryption
• 👤 Digital Personas - Complete identities with email, SMS, and 2FA for automated account creation
• 🎯 Session Management - Context managers for reliable resource cleanup
• 📡 Real-time Updates - WebSocket support for live agent monitoring
• 📝 Type Safety - Full TypeScript support with generated types
• ⚡ Serverless Functions - Run pre-built automation workflows with simple API calls
• 🔄 Auto-sync - Generated from OpenAPI spec, always up-to-date

Installation

npm install notte-sdk

Quick Start

Basic Session Usage

import { NotteClient } from 'notte-sdk';

const notte = new NotteClient({
  apiKey: 'your-api-key', // pragma: allowlist secret
  baseUrl: 'https://api.notte.cc' // optional, defaults to https://api.notte.cc
});

// Use session with automatic cleanup (mirrors Python's context manager)
await notte.Session({ timeoutMinutes: 30 }).use(async (session) => {
  const status = await session.status();
  console.log('Session status:', status);
});

Agent Automation

import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Run an agent task with live updates
await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 10 });

  const response = await agent.run(
    "Find the best Italian restaurant in San Francisco and book a table for 2 at 7pm today",
    (update) => {
      // Receive real-time updates via WebSocket
      console.log(`Step ${update.data.currentStep}: ${update.data.message}`);
    }
  );

  console.log(`Agent completed: ${response.success ? 'Success' : 'Failed'}`);
  console.log(`Answer: ${response.answer}`);
});

Core Classes

NotteClient

The main client for interacting with the Notte API.

import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create sessions
const session = notte.Session({ timeoutMinutes: 30 });

// Create agents
const agent = notte.Agent({ session, max_steps: 15 });

// Create vaults
const vault = notte.Vault({ name: 'My Vault' });

// Create personas
const persona = notte.Persona({ create_vault: true });

Session

Manages browser sessions with automatic lifecycle management.

import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Context manager pattern (automatic start/stop)
await notte.Session({ timeoutMinutes: 30 }).use(async (session) => {
  // Session is automatically started
  console.log('Session ID:', session.getId());

  const status = await session.status();
  console.log('Session status:', status);

  // Session is automatically stopped when done
});

// Manual session management
const session = notte.Session({ open_viewer: true });
await session.start();
try {
  const status = await session.status();
  console.log('Session status:', status);
} finally {
  await session.stop();
}

// Async iterator pattern
for await (const session of notte.Session({ timeoutMinutes: 15 })) {
  // Use session here
  const status = await session.status();
  console.log('Session active:', status);
  // Session automatically closed after loop
}

Session Methods

• start() - Start the session
• stop() - Stop the session
• status() - Get session status
• viewer() - Open the live session viewer in the local default browser
• use(callback) - Context manager pattern
• getId() - Get session ID
• isSessionActive() - Check if session is running

Agent

Executes tasks using LLM-powered web automation.

import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

await notte.Session().use(async (session) => {
  const agent = notte.Agent({
    session,
    max_steps: 10
  });

  // Non-blocking: start agent and get ID
  const agentId = await agent.start("Navigate to Google and search for 'TypeScript'");
  console.log('Agent started:', agentId);

  // Check agent status
  const status = await agent.status();
  console.log('Agent status:', status);

  // Blocking: run agent and wait for completion with live updates
  const response = await agent.run(
    "Find the latest TypeScript documentation",
    (update) => {
      if (update.type === 'step') {
        console.log(`Step update:`, update.data);
      } else if (update.type === 'completion') {
        console.log(`Completed:`, update.data);
      }
    }
  );

  console.log('Final result:', response);
});

Agent Methods

• start(task) - Start agent with task (non-blocking)
• run(task, onUpdate?) - Start agent and wait for completion (blocking)
• status() - Get agent status
• stop() - Stop the agent
• 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.

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.

import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a new vault
const vault = notte.Vault({ name: 'My Secure Vault' });

// Add credentials for websites
await vault.addCredentials('https://github.com/', {
  email: '[email protected]',
  password: 'secure-password', // pragma: allowlist secret
  mfa_secret: 'PYNT7I67RFS2EPR5' // pragma: allowlist secret
});

// Generate secure passwords
const strongPassword = vault.generatePassword(20, true); // 20 chars with special chars
const simplePassword = vault.generatePassword(12, false); // 12 chars, no special chars

// Add credit card information
await vault.setCreditCard({
  card_holder_name: 'John Doe',
  card_number: '4111111111111111',
  card_cvv: '123',
  expiry_month: '12',
  expiry_year: '2025'
});

// Use with agents for automatic credential management
await notte.Session().use(async (session) => {
  const agent = notte.Agent({
    session,
    vault_id: vault.vaultId // Agent will use vault for authentication
  });

  const result = await agent.run({
    task: "Login to GitHub and create a new repository",
    url: "https://github.com/login"
  });
});

// Access existing vault
const existingVault = notte.Vault({ vault_id: 'vault-abc-123' });
const credentials = await existingVault.listCredentials();

// Cleanup
await vault.deleteCredentials('https://github.com/');
await vault.deleteCreditCard();
await vault.stop(); // Deletes entire vault

Vault Methods

• addCredentials(url, credentials) - Store credentials for a URL
• getCredentials(url) - Retrieve credentials for a URL
• deleteCredentials(url) - Delete credentials for a URL
• listCredentials() - List all stored credentials
• setCreditCard(card) - Store credit card information
• getCreditCard() - Retrieve credit card information
• deleteCreditCard() - Delete credit card information
• generatePassword(length?, includeSpecialChars?) - Generate secure passwords
• delete() - Delete the entire vault
• stop() - Stop and delete the vault

Security Features

• End-to-End Encryption - All credentials encrypted at rest and in transit
• Zero Trust Architecture - Credentials never exposed to LLMs or external services
• Access Control - Strict access logging and permissions
• Two-Factor Authentication - Support for MFA secrets (TOTP)

Personas

Manage complete digital identities for automated account creation and 2FA.

import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a new persona with vault and phone number
const persona = notte.Persona({
  create_vault: true,
  create_phone_number: true
});

// Get persona information
console.log(`Email: ${persona.info.email}`);
console.log(`Phone: ${persona.info.phone_number}`);

// Read emails sent to the persona
const emails = await persona.emails({
  limit: 10,
  only_unread: true
});
console.log(`Received ${emails.length} new emails`);

// Read SMS messages for 2FA codes
const smsMessages = await persona.sms({
  limit: 5,
  only_unread: true
});
console.log(`Received ${smsMessages.length} SMS messages`);

// Use with agents for automated account creation
await notte.Session().use(async (session) => {
  const agent = notte.Agent({
    session,
    vault_id: persona.vault.vaultId // Agent will use persona's vault
  });

  const result = await agent.run(
    `Create an account on GitHub using the persona credentials`
  );
  console.log(`Account created: ${result.success}`);
});

// Access existing persona
const existingPersona = notte.Persona({ persona_id: 'persona-abc-123' });
const personaEmails = await existingPersona.emails();

// Add credentials to persona's vault
await persona.addCredentials('https://github.com/');
// This automatically generates a secure password and stores:
// - Email: persona's email
// - Password: generated secure password

// Cleanup
await persona.stop(); // Deletes persona and all associated data

Persona Methods

• emails(options?) - Read emails sent to the persona
• sms(options?) - Read SMS messages sent to the persona
• createNumber(options?) - Create a phone number for the persona
• deleteNumber() - Delete the persona's phone number
• addCredentials(url) - Add auto-generated credentials to the persona's vault
• delete() - Delete the persona
• stop() - Stop and delete the persona

Message Reading Options

const options = {
  limit: 10,              // Maximum number of messages (default: unlimited)
  only_unread: true,      // Only return unread messages (default: false)
  timedelta: '1h'         // Maximum age of messages (e.g., '1h', '30m', '24h')
};

const emails = await persona.emails(options);
const sms = await persona.sms(options);

Persona Features

• Complete Digital Identity - Unique email address and phone number
• 2FA Support - Receive and read SMS verification codes automatically
• Automated Account Creation - Seamless integration with agents for signup flows
• Vault Integration - Optional secure credential storage
• Email Management - Full email reading capabilities
• Message Tracking - Mark messages as read/unread automatically

Functions

Run pre-built automation workflows (Notte Functions) with a simple API call. Functions are serverless workflows that run on Notte's infrastructure — you provide the function_id and input variables, and get the result back.

import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a function instance
const fn = notte.NotteFunction({
  function_id: 'your-function-id',
  decryption_key: 'optional-decryption-key' // optional, for encrypted outputs
});

// Run the function with input variables
const result = await fn.run({
  url: 'https://example.com',
  query: 'extract pricing information'
});

console.log('Run ID:', result.function_run_id);

// Retrieve the run result / metadata later
const metadata = await fn.retrieve(result.function_run_id);
console.log('Status:', metadata.status); // 'active' | 'closed' | 'failed'
console.log('Result:', metadata);

Polling for completion

Since functions run asynchronously, you can poll for the result:

const fn = notte.NotteFunction({ function_id: 'your-function-id' });
const { function_run_id } = await fn.run({ url: 'https://example.com' });

// Poll until complete
let metadata;
do {
  await new Promise(r => setTimeout(r, 2000)); // wait 2s between checks
  metadata = await fn.retrieve(function_run_id);
} while (metadata.status === 'active');

if (metadata.status === 'closed') {
  console.log('Function completed successfully:', metadata);
} else {
  console.error('Function failed:', metadata);
}

Function Methods

• run(variables?) - Start a function run with optional input variables
• retrieve(functionRunId) - Get metadata/result for a specific run
• getFunctionId() - Get the function ID
• functionId - The function ID (read-only property)
• decryptionKey - The decryption key, if provided (read-only property)

Advanced Usage

Session Configuration

const session = notte.Session({
  timeoutMinutes: 45,        // Session timeout (default: 30)
  // Add other session options as supported by the API
});

Agent Configuration

const agent = notte.Agent({
  session: session,
  max_steps: 20,             // Maximum steps for agent (default: 10)
});

Error Handling

try {
  await notte.Session().use(async (session) => {
    const agent = notte.Agent({ session });
    const response = await agent.run("Complete a complex task");

    if (!response.success) {
      console.error('Agent failed:', response.error);
    }
  });
} catch (error) {
  console.error('Session error:', error);
}

WebSocket Updates

The agent.run() method provides real-time updates via WebSocket:

const response = await agent.run("Your task", (update) => {
  switch (update.type) {
    case 'step':
      console.log(`Step ${update.data.currentStep}:`, update.data);
      break;
    case 'completion':
      console.log('Task completed:', update.data);
      break;
    default:
      console.log('Update:', update);
  }
});

Legacy API Support

For backward compatibility, you can still use the legacy client creation:

import { createClient, client } from 'notte-sdk';

// Legacy method 1
const legacyClient = createClient({
  baseUrl: 'https://api.notte.cc',
  token: 'your-api-key'
});

// Legacy method 2
import { client } from 'notte-sdk';
client.setConfig({ baseUrl: 'https://api.notte.cc' });
client.interceptors.request.use((request) => {
  request.headers.set('Authorization', 'Bearer your-api-key');
  return request;
});

Python SDK Equivalence

This TypeScript SDK closely mirrors the Python SDK patterns:

Python

from notte_sdk import NotteClient

notte = NotteClient()

# Session context manager
with notte.Session(timeout_minutes=2) as session:
    status = session.status()
    print(status)

# Agent usage
with notte.Session() as session:
    agent = notte.Agent(session=session, max_steps=10)
    response = agent.run(task="Find the best italian restaurant in SF")
    print(f"Agent completed: {response.success}, answer: {response.answer}")

TypeScript

import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Session context manager equivalent
await notte.Session({ timeoutMinutes: 2 }).use(async (session) => {
  const status = await session.status();
  console.log(status);
});

// Agent usage
await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 10 });
  const response = await agent.run("Find the best italian restaurant in SF");
  console.log(`Agent completed: ${response.success}, answer: ${response.answer}`);
});

Development

Building the SDK

# Install dependencies
npm install

# Generate client from OpenAPI spec
npm run generate

# Build the SDK
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

Testing

The SDK includes comprehensive tests:

# Run all tests
npm test

# Run tests with coverage
npm run test -- --coverage

# Run specific test file
npm run test src/test/client.test.ts

Regenerating from API

The SDK is auto-generated from the Notte OpenAPI specification:

# Regenerate client code
npm run generate

This will fetch the latest API specification and update the generated client code.

TypeScript Support

The SDK is built with full TypeScript support:

import { NotteClient, SessionStatus, AgentResponse } from 'notte-sdk';

const notte = new NotteClient();

// All types are properly inferred
await notte.Session().use(async (session) => {
  const status: SessionStatus = await session.status();
  const agent = notte.Agent({ session });
  const response: AgentResponse = await agent.run("task");
});

API Reference

Types

The SDK exports all generated types from the OpenAPI specification:

import type {
  NotteClientConfig,
  SessionOptions,
  SessionStatus,
  AgentConstructor,
  AgentRunRequest,
  AgentUpdateHandler,
  VaultConstructor,
  CredentialsDict,
  CreditCardDict,
  Credential,
  PersonaConstructor,
  MessageReadOptions,
  PersonaListOptions,
  CreatePhoneNumberOptions
} from 'notte-sdk';

License

MIT

Support

For issues and questions:

• GitHub Issues: Report issues
• Documentation: docs.notte.cc
• Python SDK: notte-sdk