initial commit sentience sdk for TypeScript

Author: rcholic

README.md

@@ -0,0 +1,96 @@
+# Sentience TypeScript SDK
+
+**Status**: ✅ Week 1 Complete
+
+TypeScript SDK for Sentience AI Agent Browser Automation.
+
+## Installation
+
+```bash
+cd sdk-ts
+npm install
+npm run build
+```
+
+## Quick Start
+
+```typescript
+import { SentienceBrowser, snapshot, find, click } from './src';
+
+async function main() {
+  const browser = new SentienceBrowser(undefined, false);
+  
+  try {
+    await browser.start();
+    
+    await browser.getPage().goto('https://example.com');
+    await browser.getPage().waitForLoadState('networkidle');
+    
+    // Take snapshot
+    const snap = await snapshot(browser);
+    console.log(`Found ${snap.elements.length} elements`);
+    
+    // Find and click a link
+    const link = find(snap, 'role=link');
+    if (link) {
+      const result = await click(browser, link.id);
+      console.log(`Click success: ${result.success}`);
+    }
+  } finally {
+    await browser.close();
+  }
+}
+```
+
+## Features
+
+### Day 2: Browser Harness
+- `SentienceBrowser` - Launch Playwright with extension loaded
+- Automatic extension loading and verification
+
+### Day 3: Snapshot
+- `snapshot(browser, options)` - Capture page state
+- TypeScript types for type safety
+
+### Day 4: Query Engine
+- `query(snapshot, selector)` - Find elements matching selector
+- `find(snapshot, selector)` - Find single best match
+- String DSL: `"role=button text~'Sign in'"`
+
+### Day 5: Actions
+- `click(browser, elementId)` - Click element
+- `typeText(browser, elementId, text)` - Type into element
+- `press(browser, key)` - Press keyboard key
+
+### Day 6: Wait & Assert
+- `waitFor(browser, selector, timeout)` - Wait for element
+- `expect(browser, selector)` - Assertion helper
+  - `.toExist()`
+  - `.toBeVisible()`
+  - `.toHaveText(text)`
+  - `.toHaveCount(n)`
+
+## Examples
+
+See `examples/` directory:
+- `hello.ts` - Extension bridge verification
+- `basic-agent.ts` - Basic snapshot
+- `query-demo.ts` - Query engine
+- `wait-and-click.ts` - Wait and actions
+
+Run examples:
+```bash
+npm run example:hello
+npm run example:basic
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Documentation
+
+- API Contract: `../spec/SNAPSHOT_V1.md`
+- Type Definitions: `../spec/sdk-types.md`

examples/basic-agent.ts

@@ -0,0 +1,40 @@
+/**
+ * Day 3 Example: Basic snapshot functionality
+ */
+
+import { SentienceBrowser, snapshot } from '../src';
+import * as fs from 'fs';
+
+async function main() {
+  const browser = new SentienceBrowser(undefined, false);
+  
+  try {
+    await browser.start();
+    
+    // Navigate to a test page
+    await browser.getPage().goto('https://example.com');
+    await browser.getPage().waitForLoadState('networkidle');
+    
+    // Take snapshot
+    const snap = await snapshot(browser);
+    
+    console.log(`Status: ${snap.status}`);
+    console.log(`URL: ${snap.url}`);
+    console.log(`Elements found: ${snap.elements.length}`);
+    
+    // Show top 5 elements
+    console.log('\nTop 5 elements:');
+    snap.elements.slice(0, 5).forEach((el, i) => {
+      console.log(`${i + 1}. [${el.role}] ${el.text || '(no text)'} (importance: ${el.importance})`);
+    });
+    
+    // Save snapshot
+    fs.writeFileSync('snapshot_example.json', JSON.stringify(snap, null, 2));
+    console.log('\n✅ Snapshot saved to snapshot_example.json');
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch(console.error);
+

examples/hello.ts

@@ -0,0 +1,31 @@
+/**
+ * Day 2 Example: Verify extension bridge is loaded
+ */
+
+import { SentienceBrowser } from '../src';
+
+async function main() {
+  const browser = new SentienceBrowser(undefined, false);
+  
+  try {
+    await browser.start();
+    
+    // Check if extension API is available
+    const bridgeOk = await browser.getPage().evaluate(
+      () => typeof (window as any).sentience !== 'undefined'
+    );
+    
+    console.log(`bridge_ok=${bridgeOk}`);
+    
+    if (bridgeOk) {
+      console.log('✅ Extension loaded successfully!');
+    } else {
+      console.log('❌ Extension not loaded');
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch(console.error);
+

examples/query-demo.ts

@@ -0,0 +1,51 @@
+/**
+ * Day 4 Example: Query engine demonstration
+ */
+
+import { SentienceBrowser, snapshot, query, find } from '../src';
+
+async function main() {
+  const browser = new SentienceBrowser(undefined, false);
+  
+  try {
+    await browser.start();
+    
+    // Navigate to a page with links
+    await browser.getPage().goto('https://example.com');
+    await browser.getPage().waitForLoadState('networkidle');
+    
+    const snap = await snapshot(browser);
+    
+    // Query examples
+    console.log('=== Query Examples ===\n');
+    
+    // Find all buttons
+    const buttons = query(snap, 'role=button');
+    console.log(`Found ${buttons.length} buttons`);
+    
+    // Find all links
+    const links = query(snap, 'role=link');
+    console.log(`Found ${links.length} links`);
+    
+    // Find clickable elements
+    const clickables = query(snap, 'clickable=true');
+    console.log(`Found ${clickables.length} clickable elements`);
+    
+    // Find element with text containing "More"
+    const moreLink = find(snap, "text~'More'");
+    if (moreLink) {
+      console.log(`\nFound 'More' link: ${moreLink.text} (id: ${moreLink.id})`);
+    } else {
+      console.log('\nNo "More" link found');
+    }
+    
+    // Complex query: clickable links
+    const clickableLinks = query(snap, 'role=link clickable=true');
+    console.log(`\nFound ${clickableLinks.length} clickable links`);
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch(console.error);
+

examples/wait-and-click.ts

@@ -0,0 +1,63 @@
+/**
+ * Day 5-6 Example: Wait for element and click
+ */
+
+import { SentienceBrowser, snapshot, find, waitFor, click, expect } from '../src';
+
+async function main() {
+  const browser = new SentienceBrowser(undefined, false);
+  
+  try {
+    await browser.start();
+    
+    // Navigate to example.com
+    await browser.getPage().goto('https://example.com');
+    await browser.getPage().waitForLoadState('networkidle');
+    
+    // Take initial snapshot
+    const snap = await snapshot(browser);
+    
+    // Find a link
+    const link = find(snap, 'role=link');
+    
+    if (link) {
+      console.log(`Found link: ${link.text} (id: ${link.id})`);
+      
+      // Click it
+      const result = await click(browser, link.id);
+      console.log(`Click result: success=${result.success}, outcome=${result.outcome}`);
+      
+      // Wait for navigation
+      await browser.getPage().waitForLoadState('networkidle');
+      console.log(`New URL: ${browser.getPage().url()}`);
+    } else {
+      console.log('No link found');
+    }
+    
+    // Example: Wait for element using waitFor
+    console.log('\n=== Wait Example ===');
+    await browser.getPage().goto('https://example.com');
+    await browser.getPage().waitForLoadState('networkidle');
+    
+    const waitResult = await waitFor(browser, 'role=link', 5000);
+    if (waitResult.found) {
+      console.log(`✅ Found element after ${waitResult.duration_ms}ms`);
+    } else {
+      console.log(`❌ Element not found (timeout: ${waitResult.timeout})`);
+    }
+    
+    // Example: Expect assertion
+    console.log('\n=== Expect Example ===');
+    try {
+      const element = await expect(browser, 'role=link').toExist(5000);
+      console.log(`✅ Element exists: ${element.text}`);
+    } catch (e: any) {
+      console.log(`❌ Assertion failed: ${e.message}`);
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch(console.error);
+