Merge pull request #21 from browser-use/feat/readme

Improve README

Author: maticzav

README.md

@@ -26,32 +26,105 @@ const client = new BrowserUse({
   apiKey: process.env['BROWSER_USE_API_KEY'], // This is the default and can be omitted
 });
 
-const task = await client.tasks.create({
+// #1 - Run a task and get its result
+
+const task = await client.tasks.run({
   task: 'Search for the top 10 Hacker News posts and return the title and url.',
 });
 
-console.log(task.id);
-```
+console.log(task.doneOutput);
 
-### Request & Response types
+// #2 - Run a task with a structured result
 
-This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
+import z from 'zod';
 
-<!-- prettier-ignore -->
-```ts
-import BrowserUse from 'browser-use-sdk';
+const TaskOutput = z.object({
+  posts: z.array(
+    z.object({
+      title: z.string(),
+      url: z.string(),
+    }),
+  ),
+});
 
-const client = new BrowserUse({
-  apiKey: process.env['BROWSER_USE_API_KEY'], // This is the default and can be omitted
+const posts = await client.tasks.run({
+  task: 'Search for the top 10 Hacker News posts and return the title and url.',
 });
 
-const params: BrowserUse.TaskCreateParams = {
+for (const post of posts.doneOutput.posts) {
+  console.log(`${post.title} - ${post.url}`);
+}
+
+// #3 - Stream Task Progress
+
+const hn = await browseruse.tasks.create({
   task: 'Search for the top 10 Hacker News posts and return the title and url.',
-};
-const task: BrowserUse.TaskCreateResponse = await client.tasks.create(params);
+  schema: TaskOutput,
+});
+
+const stream = browseruse.tasks.stream({
+  taskId: hn.id,
+  schema: TaskOutput,
+});
+
+for await (const msg of stream) {
+  switch (msg.status) {
+    case 'started':
+    case 'paused':
+    case 'stopped':
+      console.log(`running: ${msg}`);
+      break;
+
+    case 'finished':
+      console.log(`done:`);
+
+      for (const post of msg.doneOutput.posts) {
+        console.log(`${post.title} - ${post.url}`);
+      }
+      break;
+  }
+}
 ```
 
-Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
+## Webhook Verification
+
+> We encourage you to use the SDK functions that verify and parse webhook events.
+
+```ts
+import {
+  verifyWebhookEventSignature,
+  type WebhookAgentTaskStatusUpdatePayload,
+} from 'browser-use-sdk/lib/webhooks';
+
+export async function POST(req: Request) {
+  const signature = req.headers['x-browser-use-signature'] as string;
+  const timestamp = req.headers['x-browser-use-timestamp'] as string;
+
+  const event = await verifyWebhookEventSignature(
+    {
+      body,
+      signature,
+      timestamp,
+    },
+    {
+      secret: SECRET_KEY,
+    },
+  );
+
+  if (!event.ok) {
+    return;
+  }
+
+  switch (event.event.type) {
+    case 'agent.task.status_update':
+      break;
+    case 'test':
+      break;
+    default:
+      break;
+  }
+}
+```
 
 ## Handling errors
 

examples/run-zod.ts

@@ -21,7 +21,7 @@ const TaskOutput = z.object({
 });
 
 async function main() {
-  console.log(`Creating Task...`);
+  console.log(`Running Task...`);
 
   // Create Task
   const rsp = await browseruse.tasks.run({

examples/run.ts

@@ -10,7 +10,7 @@ env();
 const browseruse = new BrowserUse();
 
 async function main() {
-  console.log(`Creating Task...`);
+  console.log(`Running Task...`);
 
   // Create Task
   const rsp = await browseruse.tasks.run({