From 5e22f4e2b79a5479cec2f7d229f3826f6f8f011f Mon Sep 17 00:00:00 2001
From: Matic Zavadlal <matic.zavadlal@gmail.com>
Date: Tue, 19 Aug 2025 18:53:37 +0100
Subject: [PATCH] Improve README

---
 README.md           | 101 ++++++++++++++++++++++++++++++++++++++------
 examples/run-zod.ts |   2 +-
 examples/run.ts     |   2 +-
 3 files changed, 89 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 25dbb71..5ca5e8c 100644
--- a/README.md
+++ b/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
 
diff --git a/examples/run-zod.ts b/examples/run-zod.ts
index a987d09..54c316e 100755
--- a/examples/run-zod.ts
+++ b/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({
diff --git a/examples/run.ts b/examples/run.ts
index 0f4fcb4..33982e5 100755
--- a/examples/run.ts
+++ b/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({