notte-sdk 0.0.1

package/README.md

@@ -0,0 +1,632 @@
+# 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
+
+```bash
+npm install notte-sdk
+```
+
+## Quick Start
+
+### Basic Session Usage
+
+```typescript
+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
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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();
+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
+- `use(callback)` - Context manager pattern
+- `getId()` - Get session ID
+- `isSessionActive()` - Check if session is running
+
+### Agent
+
+Executes tasks using LLM-powered web automation.
+
+```typescript
+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
+
+### Secret Vaults
+
+Manage credentials securely with enterprise-grade encryption.
+
+```typescript
+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: 'user@example.com',
+  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.
+
+```typescript
+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
+
+```typescript
+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.
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+const session = notte.Session({
+  timeoutMinutes: 45,        // Session timeout (default: 30)
+  // Add other session options as supported by the API
+});
+```
+
+### Agent Configuration
+
+```typescript
+const agent = notte.Agent({
+  session: session,
+  max_steps: 20,             // Maximum steps for agent (default: 10)
+});
+```
+
+### Error Handling
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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
+```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
+```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
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```typescript
+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:
+
+```typescript
+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](https://github.com/notte/sdk/issues)
+- Documentation: [docs.notte.cc](https://docs.notte.cc)
+- Python SDK: [notte-sdk](https://pypi.org/project/notte-sdk/)