@tiny-fish/sdk 0.0.3 → 0.0.6

package/README.md

@@ -1,5 +1,501 @@
 # TinyFish TypeScript SDK
 
-State-of-the-art web agents in an API.
+The official TypeScript SDK for [TinyFish](https://agent.tinyfish.ai)
 
-> Currently this SDK is still being built. Discuss with @simantak-dabhade
+For SDK design conventions and how new API surfaces should be added, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Installation
+
+```bash
+npm install @tiny-fish/sdk
+```
+
+Requires Node.js 18+. Also works with Bun and Deno.
+
+## Get your API key
+
+Sign up and grab your key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).
+
+## Quickstart
+
+```typescript
+import { TinyFish } from "@tiny-fish/sdk";
+
+const client = new TinyFish({ apiKey: "your-api-key" });
+
+const stream = await client.agent.stream(
+  {
+    goal: "What is the current Bitcoin price?",
+    url: "https://www.coinbase.com/price/bitcoin",
+  },
+  {
+    onProgress: (e) => console.log(`  > ${e.purpose}`),
+    onComplete: (e) => console.log(e.result),
+  },
+);
+
+for await (const event of stream) {
+  // Callbacks fire automatically during iteration
+}
+```
+
+Need per-request cancellation without changing the client-wide timeout? Pass an `AbortSignal` as the optional second argument:
+
+```typescript
+const controller = new AbortController();
+
+const stream = await client.agent.stream(
+  {
+    goal: "Extract the top 5 headlines",
+    url: "https://news.ycombinator.com",
+  },
+  {
+    signal: controller.signal,
+  },
+);
+
+controller.abort();
+```
+
+Or set the `TINYFISH_API_KEY` environment variable and omit `apiKey`:
+
+```typescript
+const client = new TinyFish();
+```
+
+> All methods are async and return promises. There is no synchronous client — JavaScript is async-native.
+
+## Methods
+
+| Method | Description | Returns | Blocks? |
+|--------|-------------|---------|---------|
+| [`agent.stream()`](#agentstream--real-time-events) | Stream live SSE events as the agent works | `AgentStream` | No |
+| [`agent.run()`](#agentrun--block-until-done) | Run an automation, wait for the result | `AgentRunResponse` | Yes |
+| [`agent.queue()`](#agentqueue--fire-and-forget) | Start an automation, return immediately | `AgentRunAsyncResponse` | No |
+| [`browser.sessions.create()`](#browsersessionscreate--create-a-browser-session) | Create a remote browser session | `BrowserSession` | — |
+| [`fetch.getContents()`](#fetchgetcontents--fetch-and-extract-content) | Fetch URLs and return extracted content | `FetchResponse` | — |
+| [`runs.get()`](#runsget--retrieve-a-single-run) | Retrieve a single run by ID | `Run` | — |
+| [`runs.list()`](#runslist--list-and-filter-runs) | List runs with filtering, sorting, pagination | `RunListResponse` | — |
+| [`search.query()`](#searchquery--run-a-web-search) | Run a web search query | `SearchQueryResponse` | — |
+
+---
+
+### `agent.stream()` — real-time events
+
+Opens a Server-Sent Events stream. You get live progress updates as the agent works, plus a URL for a live browser preview. This is the recommended integration method.
+
+```typescript
+import { TinyFish } from "@tiny-fish/sdk";
+
+const client = new TinyFish();
+
+const stream = await client.agent.stream(
+  {
+    goal: "Extract the top 5 headlines",
+    url: "https://news.ycombinator.com",
+  },
+  {
+    onStarted: (e) => console.log(`Started: ${e.run_id}`),
+    onStreamingUrl: (e) => console.log(`Watch: ${e.streaming_url}`),
+    onProgress: (e) => console.log(`  > ${e.purpose}`),
+    onComplete: (e) => console.log(`Done: ${e.status}`),
+  },
+);
+
+for await (const event of stream) {
+  // Callbacks fire automatically during iteration.
+  // You can also inspect events directly:
+  if (event.type === "COMPLETE") {
+    console.log(event.result);
+  }
+}
+```
+
+**Returns `AgentStream`** — an async iterable you iterate with `for await`. Events arrive in order: `STARTED` → `STREAMING_URL` → `PROGRESS` (repeated) → `COMPLETE`.
+
+Call `stream.close()` to abort early and stop yielding events.
+
+The second argument also accepts `signal` for request-scoped cancellation:
+
+```typescript
+const controller = new AbortController();
+
+const stream = await client.agent.stream(
+  {
+    goal: "Extract the top 5 headlines",
+    url: "https://news.ycombinator.com",
+  },
+  {
+    signal: controller.signal,
+    onProgress: (e) => console.log(e.purpose),
+  },
+);
+
+controller.abort();
+```
+
+See the [Streaming Guide](docs/streaming-guide.md) for the full event lifecycle, event types, and advanced patterns.
+
+---
+
+### `agent.run()` — block until done
+
+Sends the automation and waits for it to finish. Returns the full result in one shot.
+
+```typescript
+import { TinyFish, RunStatus, BrowserProfile, ProxyCountryCode } from "@tiny-fish/sdk";
+import type { ProxyConfig } from "@tiny-fish/sdk";
+
+const client = new TinyFish();
+
+const response = await client.agent.run({
+  goal: "Extract the top 5 headlines",              // required — what to do on the page
+  url: "https://news.ycombinator.com",              // required — URL to open
+  browser_profile: BrowserProfile.STEALTH,           // optional — "lite" (default) or "stealth"
+  proxy_config: {                                    // optional — proxy settings
+    enabled: true,
+    country_code: ProxyCountryCode.US,               // optional — US, GB, CA, DE, FR, JP, AU
+  },
+});
+
+if (response.status === RunStatus.COMPLETED) {
+  console.log(response.result);
+} else {
+  console.log(`Failed: ${response.error?.message}`);
+}
+```
+
+Like `stream()`, `run()` accepts an optional second argument with `signal`:
+
+```typescript
+const controller = new AbortController();
+
+const response = await client.agent.run(
+  {
+    goal: "Extract the top 5 headlines",
+    url: "https://news.ycombinator.com",
+  },
+  {
+    signal: controller.signal,
+  },
+);
+```
+
+**Returns `AgentRunResponse`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `RunStatus` | `COMPLETED`, `FAILED`, etc. |
+| `run_id` | `string \| null` | Unique run identifier |
+| `result` | `Record<string, unknown> \| null` | Extracted data (`null` if failed) |
+| `error` | `RunError \| null` | Error details (`null` if succeeded) |
+| `num_of_steps` | `number` | Number of steps the agent took |
+| `started_at` | `string \| null` | ISO 8601 timestamp when the run started |
+| `finished_at` | `string \| null` | ISO 8601 timestamp when the run finished |
+
+---
+
+### `agent.queue()` — fire and forget
+
+Starts the automation in the background and returns a `run_id` immediately. Poll with `runs.get()` when you're ready for the result.
+
+```typescript
+import { TinyFish, RunStatus } from "@tiny-fish/sdk";
+
+const client = new TinyFish();
+
+const queued = await client.agent.queue({
+  goal: "Extract the top 5 headlines",
+  url: "https://news.ycombinator.com",
+});
+
+if (queued.error) {
+  console.error(`Failed to queue: ${queued.error.message}`);
+  process.exit(1);
+}
+
+console.log(`Run started: ${queued.run_id}`);
+
+// Poll for completion
+while (true) {
+  const run = await client.runs.get(queued.run_id);
+  if (run.status === RunStatus.COMPLETED || run.status === RunStatus.FAILED) {
+    console.log(run.result);
+    break;
+  }
+  await new Promise((r) => setTimeout(r, 5000));
+}
+```
+
+`queue()` also accepts an optional `{ signal }` second argument when you want to cancel just that enqueue request.
+
+**Returns `AgentRunAsyncResponse`** — a discriminated union. Check `error` to narrow the type:
+
+```typescript
+const response = await client.agent.queue({ goal, url });
+if (response.error) {
+  // response.run_id is null here
+  console.error(response.error.message);
+} else {
+  // response.run_id is string here
+  const run = await client.runs.get(response.run_id);
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `run_id` | `string \| null` | Run ID to poll with `runs.get()` |
+| `error` | `RunError \| null` | Error if queuing itself failed |
+
+---
+
+### `browser.sessions.create()` — create a browser session
+
+Create a remote browser session and get back the connection details for direct CDP control. Pass a `url` to hint routing and start the session on a target page, or omit it to start at `about:blank`.
+
+```typescript
+import { TinyFish } from "@tiny-fish/sdk";
+
+const client = new TinyFish();
+
+const session = await client.browser.sessions.create({
+  url: "https://example.com",
+});
+
+console.log(session.session_id);
+console.log(session.cdp_url);
+console.log(session.base_url);
+```
+
+**Returns `BrowserSession`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `session_id` | `string` | Unique browser session identifier |
+| `cdp_url` | `string` | CDP WebSocket URL for connecting to the browser |
+| `base_url` | `string` | HTTPS base URL for the browser session |
+
+---
+
+### `fetch.getContents()` — fetch and extract content
+
+Fetch one or more URLs and return clean extracted content in markdown, html, or json form.
+
+```typescript
+import { FetchFormat, TinyFish } from "@tiny-fish/sdk";
+
+const client = new TinyFish();
+
+const response = await client.fetch.getContents({
+  urls: ["https://example.com"],
+  format: FetchFormat.Markdown,
+  links: true,
+  image_links: false,
+});
+
+console.log(response.results);
+console.log(response.errors);
+```
+
+**Returns `FetchResponse`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `results` | `FetchResult[]` | Successfully fetched URLs and extracted content |
+| `errors` | `FetchError[]` | URLs that failed to fetch |
+
+`FetchResult.text` is:
+
+- `string` for `markdown` and `html`
+- `Record<string, unknown>` for `json`
+- `null` if extraction failed for that item
+
+---
+
+### `runs.get()` — retrieve a single run
+
+Fetch the full details of a run by its ID.
+
+```typescript
+const run = await client.runs.get("run_abc123");
+
+console.log(run.status);          // PENDING, RUNNING, COMPLETED, FAILED, CANCELLED
+console.log(run.result);
+console.log(run.goal);
+console.log(run.streaming_url);   // live browser URL (while RUNNING)
+console.log(run.browser_config);  // proxy/browser settings that were used
+```
+
+**Returns `Run`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `run_id` | `string` | Unique identifier |
+| `status` | `RunStatus` | `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED` |
+| `goal` | `string` | The goal that was given |
+| `result` | `Record<string, unknown> \| null` | Extracted data (`null` if not completed) |
+| `error` | `RunError \| null` | Error details (`null` if succeeded) |
+| `streaming_url` | `string \| null` | Live browser URL (available while running) |
+| `browser_config` | `BrowserConfig \| null` | Proxy/browser settings used |
+| `created_at` | `string` | ISO 8601 timestamp when the run was created |
+| `started_at` | `string \| null` | ISO 8601 timestamp when execution started |
+| `finished_at` | `string \| null` | ISO 8601 timestamp when execution finished |
+| `num_of_steps` | `number` | Number of steps the agent took |
+
+**Throws:** `SDKError` if `run_id` is empty. `NotFoundError` if no run exists with that ID.
+
+---
+
+### `runs.list()` — list and filter runs
+
+List runs with optional filtering, sorting, and cursor-based pagination. All parameters are optional.
+
+```typescript
+import { RunStatus, SortDirection } from "@tiny-fish/sdk";
+
+const response = await client.runs.list({
+  status: RunStatus.COMPLETED,                     // optional — filter by status
+  goal: "headlines",                               // optional — filter by goal text
+  created_after: "2025-01-01T00:00:00Z",           // optional — ISO 8601 lower bound
+  created_before: "2025-12-31T23:59:59Z",          // optional — ISO 8601 upper bound
+  sort_direction: SortDirection.DESC,               // optional — "asc" or "desc"
+  limit: 10,                                       // optional — max runs per page
+  cursor: undefined,                               // optional — pagination cursor from previous response
+});
+
+for (const run of response.data) {
+  console.log(`${run.run_id} | ${run.goal}`);
+}
+
+// Pagination
+if (response.pagination.has_more) {
+  const nextPage = await client.runs.list({ cursor: response.pagination.next_cursor! });
+}
+```
+
+**Returns `RunListResponse`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `data` | `Run[]` | List of runs |
+| `pagination.total` | `number` | Total runs matching filters |
+| `pagination.has_more` | `boolean` | Whether more pages exist |
+| `pagination.next_cursor` | `string \| null` | Pass to `cursor` for the next page |
+
+See the [Pagination Guide](docs/pagination-guide.md) for full pagination loop examples.
+
+---
+
+### `search.query()` — run a web search
+
+Run a typed search query through the TinyFish Search API.
+
+```typescript
+import { TinyFish } from "@tiny-fish/sdk";
+
+const client = new TinyFish();
+
+const response = await client.search.query({
+  query: "tinyfish sdk",
+  location: "US",
+  language: "en",
+});
+
+console.log(response.query);
+console.log(response.total_results);
+console.log(response.results[0]?.title);
+```
+
+**Returns `SearchQueryResponse`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `query` | `string` | The query that was executed |
+| `results` | `SearchResult[]` | Search results returned by the backend |
+| `total_results` | `number` | Total number of results returned |
+
+**Throws:** `SDKError` if `query` is empty. Standard API errors are handled by the shared SDK error hierarchy.
+
+---
+
+## Configuration
+
+### Client options
+
+```typescript
+const client = new TinyFish({
+  apiKey: "your-api-key",                    // optional — or set TINYFISH_API_KEY env var
+  baseURL: "https://agent.tinyfish.ai",      // optional — default shown
+  timeout: 600_000,                          // optional — milliseconds (default: 600,000 = 10 min)
+  maxRetries: 2,                             // optional — retry attempts (default: 2)
+});
+```
+
+The SDK retries `408`, `429`, and `5xx` errors automatically with exponential backoff (0.5s base, max 8s wait).
+
+### Browser profiles
+
+Control the browser environment with `browser_profile`:
+
+- **`lite`** (default) — fast, lightweight. Good for most sites.
+- **`stealth`** — anti-detection mode. Use for sites with bot protection.
+
+```typescript
+import { BrowserProfile } from "@tiny-fish/sdk";
+
+const response = await client.agent.run({
+  goal: "...",
+  url: "...",
+  browser_profile: BrowserProfile.STEALTH,
+});
+```
+
+### Proxy configuration
+
+Route requests through a proxy, optionally pinned to a country:
+
+```typescript
+import { ProxyCountryCode } from "@tiny-fish/sdk";
+
+const response = await client.agent.run({
+  goal: "...",
+  url: "...",
+  proxy_config: { enabled: true, country_code: ProxyCountryCode.US },
+});
+```
+
+Available countries: `US`, `GB`, `CA`, `DE`, `FR`, `JP`, `AU`.
+
+See the [Proxy & Browser Profiles Guide](docs/proxy-and-browser-profiles.md) for more details.
+
+## Error handling
+
+```typescript
+import { TinyFish, AuthenticationError, RateLimitError, SDKError } from "@tiny-fish/sdk";
+
+const client = new TinyFish();
+
+try {
+  const response = await client.agent.run({ goal: "...", url: "..." });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.log("Invalid API key");
+  } else if (error instanceof RateLimitError) {
+    console.log("Rate limited (retries exhausted)");
+  } else if (error instanceof SDKError) {
+    console.log("Something else went wrong");
+  }
+}
+```
+
+The SDK automatically retries transient errors (`408`, `429`, `5xx`) up to `maxRetries` times with exponential backoff. Non-retryable errors (`401`, `400`, `404`) throw immediately.
+
+For the full exception hierarchy and internal architecture, see [docs/internal/exceptions-and-errors-guide.md](docs/internal/exceptions-and-errors-guide.md).
+
+## Guides
+
+- [Streaming Guide](docs/streaming-guide.md) — event lifecycle, callbacks vs iteration, event type reference
+- [Proxy & Browser Profiles](docs/proxy-and-browser-profiles.md) — stealth mode, proxy countries
+- [Pagination Guide](docs/pagination-guide.md) — filtering, sorting, cursor-based pagination
+- [Exceptions & Error Handling (internal)](docs/internal/exceptions-and-errors-guide.md) — layer-by-layer architecture
+- [Testing Guide](tests/testing-guide.md) — running and writing tests

package/dist/_utils/client.d.ts

@@ -7,6 +7,15 @@ export interface ClientOptions {
     timeout?: number;
     maxRetries?: number;
 }
+interface RequestOptions {
+    signal?: AbortSignal | undefined;
+}
+interface GetRequestOptions extends RequestOptions {
+    params?: Record<string, string | number | boolean | undefined>;
+}
+interface PostRequestOptions extends RequestOptions {
+    json?: unknown;
+}
 export declare class BaseClient {
     private readonly _apiKey;
     readonly baseURL: string;
@@ -18,6 +27,9 @@ export declare class BaseClient {
      */
     toJSON(): Record<string, unknown>;
     protected _buildHeaders(): Record<string, string>;
+    /** Inject api_integration from TF_API_INTEGRATION env var into JSON body. */
+    private static _injectIntegration;
+    private _buildRequestSignal;
     /**
      * Core request method with retry and error mapping.
      * All public methods (get, post, postStream) delegate here.
@@ -31,14 +43,9 @@ export declare class BaseClient {
     private _parseErrorMessage;
     /** Maps HTTP status codes to typed error classes. Matches Python SDK's _make_status_error. */
     private _makeStatusError;
-    get<T>(path: string, options?: {
-        params?: Record<string, string | number | boolean | undefined>;
-    }): Promise<T>;
-    post<T>(path: string, options?: {
-        json?: unknown;
-    }): Promise<T>;
-    postStream(path: string, options?: {
-        json?: unknown;
-    }): Promise<ReadableStream<string>>;
+    get<T>(path: string, options?: GetRequestOptions): Promise<T>;
+    post<T>(path: string, options?: PostRequestOptions): Promise<T>;
+    postStream(path: string, options?: PostRequestOptions): Promise<ReadableStream<string>>;
 }
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/_utils/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/_utils/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAqBH,MAAM,WAAW,aAAa;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,OAAO,GAAE,aAAkB;IAcvC;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAejC,SAAS,CAAC,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAUjD;;;OAGG;YACW,QAAQ;IAyDtB;;;;OAIG;YACW,kBAAkB;IAuBhC,8FAA8F;YAChF,gBAAgB;IAmCxB,GAAG,CAAC,CAAC,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;KAAE,GAC1E,OAAO,CAAC,CAAC,CAAC;IAgBP,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAK/D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;CAS7F"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/_utils/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAqBH,MAAM,WAAW,aAAa;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,cAAc;IACvB,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC;AAED,UAAU,iBAAkB,SAAQ,cAAc;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CAC/D;AAED,UAAU,kBAAmB,SAAQ,cAAc;IAClD,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAYD,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,OAAO,GAAE,aAAkB;IAcvC;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAejC,SAAS,CAAC,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAUjD,6EAA6E;IAC7E,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAYjC,OAAO,CAAC,mBAAmB;IAyC3B;;;OAGG;YACW,QAAQ;IAmFtB;;;;OAIG;YACW,kBAAkB;IAuBhC,8FAA8F;YAChF,gBAAgB;IAmCxB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC;IAgB7D,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAK/D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;CAS7F"}