@tiny-fish/sdk 0.0.1

package/dist/runs/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Runs management request/response types.
+ */
+import type { RunError, RunStatus } from "../agent/types.js";
+/** Sort order for list queries. */
+export declare enum SortDirection {
+    ASC = "asc",
+    DESC = "desc"
+}
+/** Browser configuration used for a run. */
+export interface BrowserConfig {
+    /** Whether proxy was enabled. */
+    proxy_enabled: boolean | null;
+    /** Country code for proxy. */
+    proxy_country_code: string | null;
+}
+/** A single automation run with full details. */
+export interface Run {
+    /** Unique identifier for the run. */
+    run_id: string;
+    /** Current status of the run. */
+    status: RunStatus;
+    /** Natural language goal for this automation run. */
+    goal: string;
+    /** ISO 8601 timestamp when run was created. */
+    created_at: string;
+    /** ISO 8601 timestamp when run started executing. */
+    started_at: string | null;
+    /** ISO 8601 timestamp when run finished executing. */
+    finished_at: string | null;
+    /** Number of steps taken during the automation. */
+    num_of_steps: number;
+    /** Extracted data from the automation run. `null` if not completed or failed. */
+    result: Record<string, unknown> | null;
+    /** Error details. `null` if the run succeeded or is still running. */
+    error: RunError | null;
+    /** URL to watch live browser session (available while running). */
+    streaming_url: string | null;
+    /** Browser configuration used for the run. */
+    browser_config: BrowserConfig | null;
+}
+/** Pagination metadata for list responses. */
+export interface PaginationInfo {
+    /** Total number of runs matching the current filters. */
+    total: number;
+    /** Whether there are more results after this page. */
+    has_more: boolean;
+    /** Cursor for fetching next page. `null` if no more results. */
+    next_cursor: string | null;
+}
+/** Paginated list of automation runs. */
+export interface RunListResponse {
+    /** Array of runs. */
+    data: Run[];
+    /** Pagination information. */
+    pagination: PaginationInfo;
+}
+/** Parameters for listing runs. */
+export interface RunListParams {
+    /** Pagination cursor from a previous response's `next_cursor` field. */
+    cursor?: string;
+    /** Maximum number of runs to return. */
+    limit?: number;
+    /** Filter by run status. */
+    status?: RunStatus;
+    /** Filter by goal text. */
+    goal?: string;
+    /** Filter runs created after this ISO timestamp. */
+    created_after?: string;
+    /** Filter runs created before this ISO timestamp. */
+    created_before?: string;
+    /** Sort order — `"asc"` or `"desc"`. */
+    sort_direction?: SortDirection;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runs/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE7D,mCAAmC;AACnC,oBAAY,aAAa;IACxB,GAAG,QAAQ;IACX,IAAI,SAAS;CACb;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC7B,iCAAiC;IACjC,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,8BAA8B;IAC9B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,iDAAiD;AACjD,MAAM,WAAW,GAAG;IACnB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,EAAE,SAAS,CAAC;IAClB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,sDAAsD;IACtD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,sEAAsE;IACtE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8CAA8C;IAC9C,cAAc,EAAE,aAAa,GAAG,IAAI,CAAC;CACrC;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC9B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,QAAQ,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC/B,qBAAqB;IACrB,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,8BAA8B;IAC9B,UAAU,EAAE,cAAc,CAAC;CAC3B;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B"}

package/dist/runs/types.js

@@ -0,0 +1,10 @@
+/**
+ * Runs management request/response types.
+ */
+/** Sort order for list queries. */
+export var SortDirection;
+(function (SortDirection) {
+    SortDirection["ASC"] = "asc";
+    SortDirection["DESC"] = "desc";
+})(SortDirection || (SortDirection = {}));
+//# sourceMappingURL=types.js.map

package/dist/runs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/runs/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,mCAAmC;AACnC,MAAM,CAAN,IAAY,aAGX;AAHD,WAAY,aAAa;IACxB,4BAAW,CAAA;IACX,8BAAa,CAAA;AACd,CAAC,EAHW,aAAa,KAAb,aAAa,QAGxB"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.0.1";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+// Auto-generated by scripts/generate-version.ts — do not edit manually.
+export const VERSION = "0.0.1";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@tiny-fish/sdk",
+  "version": "0.0.1",
+  "description": "TinyFish TypeScript SDK — State-of-the-art web agents in an API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "generate:version": "bun scripts/generate-version.ts",
+    "prebuild": "bun run generate:version",
+    "build": "bunx tsc -p tsconfig.build.json",
+    "prepack": "bun run build",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "biome check src/ tests/ scripts/ playground/",
+    "format": "biome format --write src/ tests/ scripts/ playground/",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/bun": "^1.3.10",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "p-retry": "^7.1.1"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "restricted"
+  }
+}

package/src/_utils/client.ts

@@ -0,0 +1,219 @@
+/**
+ * Base HTTP client — handles auth, headers, retries, and error mapping.
+ */
+
+import pRetry, { AbortError } from "p-retry";
+
+import { VERSION } from "../version.js";
+import {
+	APIConnectionError,
+	APIStatusError,
+	APITimeoutError,
+	AuthenticationError,
+	BadRequestError,
+	ConflictError,
+	InternalServerError,
+	NotFoundError,
+	PermissionDeniedError,
+	RateLimitError,
+	RequestTimeoutError,
+	SDKError,
+	UnprocessableEntityError,
+} from "./errors.js";
+
+export interface ClientOptions {
+	apiKey?: string;
+	baseURL?: string;
+	timeout?: number;
+	maxRetries?: number;
+}
+
+const DEFAULT_BASE_URL = "https://agent.tinyfish.ai";
+const DEFAULT_TIMEOUT = 600_000; // 10 minutes, matches Python SDK
+const DEFAULT_MAX_RETRIES = 2;
+
+export class BaseClient {
+	readonly apiKey: string;
+	readonly baseURL: string;
+	readonly timeout: number;
+	readonly maxRetries: number;
+
+	constructor(options: ClientOptions = {}) {
+		const apiKey = options.apiKey ?? process.env["TINYFISH_API_KEY"];
+		if (!apiKey) {
+			throw new SDKError(
+				"Missing API key. Pass `apiKey` to the constructor or set the TINYFISH_API_KEY environment variable.",
+			);
+		}
+
+		this.apiKey = apiKey;
+		this.baseURL = options.baseURL ?? DEFAULT_BASE_URL;
+		this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+		this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+	}
+
+	protected _buildHeaders(): Record<string, string> {
+		return {
+			"X-API-Key": this.apiKey,
+			"Content-Type": "application/json",
+			Accept: "application/json",
+			"User-Agent": `tinyfish-typescript/${VERSION}`,
+		};
+	}
+
+	/**
+	 * Core request method with retry and error mapping.
+	 * All public methods (get, post, postStream) delegate here.
+	 */
+	private async _request(method: string, path: string, body?: unknown): Promise<Response> {
+		const url = `${this.baseURL}${path}`;
+		const headers = this._buildHeaders();
+
+		return pRetry(
+			async () => {
+				try {
+					const response = await fetch(url, {
+						method,
+						headers,
+						body: body !== undefined ? JSON.stringify(body) : undefined,
+						signal: AbortSignal.timeout(this.timeout),
+					});
+
+					if (response.ok) {
+						return response;
+					}
+
+					const sdkError = await this._makeStatusError(response);
+
+					// Non-retryable status codes abort immediately
+					const status = response.status;
+					if (status !== 408 && status !== 429 && status < 500) {
+						throw new AbortError(sdkError);
+					}
+
+					// Retryable — let p-retry handle backoff
+					throw sdkError;
+				} catch (error) {
+					// Re-throw AbortError and SDK errors as-is
+					if (error instanceof AbortError || error instanceof SDKError) {
+						throw error;
+					}
+
+					// AbortSignal.timeout throws a DOMException with name "TimeoutError"
+					if (error instanceof DOMException && error.name === "TimeoutError") {
+						throw new APITimeoutError(`Request timed out after ${this.timeout}ms`);
+					}
+
+					// Network failures (DNS, refused, etc.)
+					throw new APIConnectionError(
+						error instanceof Error ? error.message : "Connection failed",
+					);
+				}
+			},
+			{
+				retries: this.maxRetries,
+				minTimeout: 500,
+				maxTimeout: 8_000,
+				factor: 2,
+			},
+		);
+	}
+
+	/**
+	 * Extracts a human-readable error message from the response body.
+	 * Tries JSON body → error.message → message, falls back to text, then HTTP status.
+	 * Matches Python SDK's _parse_error_message.
+	 */
+	private async _parseErrorMessage(response: Response): Promise<string> {
+		try {
+			const text = await response.text();
+			try {
+				const body = JSON.parse(text) as Record<string, unknown> | null | undefined;
+				const errorObj = body?.["error"] as Record<string, unknown> | null | undefined;
+				const msg = (errorObj?.["message"] as string) ?? (body?.["message"] as string);
+				if (typeof msg === "string" && msg.length > 0) {
+					return msg;
+				}
+			} catch {
+				// Not JSON — fall through to use raw text
+			}
+			if (text.length > 0) {
+				return text;
+			}
+		} catch {
+			// Body read failed entirely
+		}
+
+		return `HTTP ${response.status}`;
+	}
+
+	/** Maps HTTP status codes to typed error classes. Matches Python SDK's _make_status_error. */
+	private async _makeStatusError(response: Response): Promise<SDKError> {
+		const msg = await this._parseErrorMessage(response);
+		const opts = { response };
+
+		switch (response.status) {
+			case 400:
+				return new BadRequestError(msg, opts);
+			case 401:
+				return new AuthenticationError(msg, opts);
+			case 403:
+				return new PermissionDeniedError(msg, opts);
+			case 404:
+				return new NotFoundError(msg, opts);
+			case 408:
+				return new RequestTimeoutError(msg, opts);
+			case 409:
+				return new ConflictError(msg, opts);
+			case 422:
+				return new UnprocessableEntityError(msg, opts);
+			case 429:
+				return new RateLimitError(msg, opts);
+			default:
+				if (response.status >= 500) {
+					return new InternalServerError(msg, {
+						response,
+						statusCode: response.status,
+					});
+				}
+				return new APIStatusError(msg, {
+					response,
+					statusCode: response.status,
+				});
+		}
+	}
+
+	async get<T>(
+		path: string,
+		options?: { params?: Record<string, string | number | boolean | undefined> },
+	): Promise<T> {
+		let url = path;
+		if (options?.params) {
+			const filtered: Record<string, string> = {};
+			for (const [key, value] of Object.entries(options.params)) {
+				if (value !== undefined) {
+					filtered[key] = String(value);
+				}
+			}
+			const searchParams = new URLSearchParams(filtered);
+			url = `${path}?${searchParams.toString()}`;
+		}
+		const response = await this._request("GET", url);
+		return (await response.json()) as T;
+	}
+
+	async post<T>(path: string, options?: { json?: unknown }): Promise<T> {
+		const response = await this._request("POST", path, options?.json);
+		return (await response.json()) as T;
+	}
+
+	async postStream(path: string, options?: { json?: unknown }): Promise<ReadableStream<string>> {
+		const response = await this._request("POST", path, options?.json);
+
+		if (!response.body) {
+			throw new SDKError("Response body is null — server did not return a stream");
+		}
+
+		return response.body.pipeThrough(new TextDecoderStream());
+	}
+}

package/src/_utils/errors.ts

@@ -0,0 +1,153 @@
+/**
+ * Exception hierarchy for SDK errors.
+ *
+ * Hierarchy:
+ *   SDKError
+ *   +- SSEParseError
+ *   +- APIError
+ *      +- APIConnectionError
+ *      |  +- APITimeoutError
+ *      +- APIStatusError
+ *         +- BadRequestError (400)
+ *         +- AuthenticationError (401)
+ *         +- PermissionDeniedError (403)
+ *         +- NotFoundError (404)
+ *         +- RequestTimeoutError (408)
+ *         +- ConflictError (409)
+ *         +- UnprocessableEntityError (422)
+ *         +- RateLimitError (429)
+ *         +- InternalServerError (500+)
+ */
+
+export class SDKError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "SDKError";
+	}
+}
+
+export class SSEParseError extends SDKError {
+	readonly line: string;
+
+	constructor(message: string, line: string) {
+		super(message);
+		this.name = "SSEParseError";
+		this.line = line;
+	}
+}
+
+export class APIError extends SDKError {
+	readonly request: Request | undefined;
+	readonly response: Response | undefined;
+
+	constructor(
+		message: string,
+		options?: { request?: Request | undefined; response?: Response | undefined },
+	) {
+		super(message);
+		this.name = "APIError";
+		this.request = options?.request;
+		this.response = options?.response;
+	}
+}
+
+export class APIConnectionError extends APIError {
+	constructor(message: string, options?: { request?: Request | undefined }) {
+		super(message, options);
+		this.name = "APIConnectionError";
+	}
+}
+
+export class APITimeoutError extends APIConnectionError {
+	constructor(message: string, options?: { request?: Request | undefined }) {
+		super(message, options);
+		this.name = "APITimeoutError";
+	}
+}
+
+export class APIStatusError extends APIError {
+	readonly statusCode: number;
+
+	constructor(
+		message: string,
+		options: { response: Response; statusCode: number; request?: Request | undefined },
+	) {
+		super(message, { request: options.request, response: options.response });
+		this.name = "APIStatusError";
+		this.statusCode = options.statusCode;
+	}
+}
+
+export class BadRequestError extends APIStatusError {
+	constructor(message: string, options: { response: Response; request?: Request | undefined }) {
+		super(message, { ...options, statusCode: 400 });
+		this.name = "BadRequestError";
+	}
+}
+
+export class AuthenticationError extends APIStatusError {
+	constructor(message: string, options: { response: Response; request?: Request | undefined }) {
+		super(message, { ...options, statusCode: 401 });
+		this.name = "AuthenticationError";
+	}
+}
+
+export class PermissionDeniedError extends APIStatusError {
+	constructor(message: string, options: { response: Response; request?: Request | undefined }) {
+		super(message, { ...options, statusCode: 403 });
+		this.name = "PermissionDeniedError";
+	}
+}
+
+export class NotFoundError extends APIStatusError {
+	constructor(message: string, options: { response: Response; request?: Request | undefined }) {
+		super(message, { ...options, statusCode: 404 });
+		this.name = "NotFoundError";
+	}
+}
+
+export class RequestTimeoutError extends APIStatusError {
+	constructor(message: string, options: { response: Response; request?: Request | undefined }) {
+		super(message, { ...options, statusCode: 408 });
+		this.name = "RequestTimeoutError";
+	}
+}
+
+export class ConflictError extends APIStatusError {
+	constructor(message: string, options: { response: Response; request?: Request | undefined }) {
+		super(message, { ...options, statusCode: 409 });
+		this.name = "ConflictError";
+	}
+}
+
+export class UnprocessableEntityError extends APIStatusError {
+	constructor(message: string, options: { response: Response; request?: Request | undefined }) {
+		super(message, { ...options, statusCode: 422 });
+		this.name = "UnprocessableEntityError";
+	}
+}
+
+export class RateLimitError extends APIStatusError {
+	constructor(message: string, options: { response: Response; request?: Request | undefined }) {
+		super(message, { ...options, statusCode: 429 });
+		this.name = "RateLimitError";
+	}
+}
+
+export class InternalServerError extends APIStatusError {
+	constructor(
+		message: string,
+		options: {
+			response: Response;
+			statusCode?: number | undefined;
+			request?: Request | undefined;
+		},
+	) {
+		super(message, {
+			response: options.response,
+			statusCode: options.statusCode ?? 500,
+			request: options.request,
+		});
+		this.name = "InternalServerError";
+	}
+}

package/src/_utils/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Reusable SDK foundation.
+ *
+ * Provides base classes for building HTTP API SDKs:
+ * - Client: HTTP client with auth and request plumbing
+ * - Resource: Base class for API resource groupings
+ * - Errors: Complete error hierarchy
+ * - SSE: Server-sent events parser
+ */
+
+export { BaseClient } from "./client.js";
+export type { ClientOptions } from "./client.js";
+export { APIResource } from "./resource.js";
+export { parseSSEStream } from "./sse.js";
+export {
+	SDKError,
+	SSEParseError,
+	APIError,
+	APIConnectionError,
+	APITimeoutError,
+	APIStatusError,
+	BadRequestError,
+	AuthenticationError,
+	PermissionDeniedError,
+	NotFoundError,
+	RequestTimeoutError,
+	ConflictError,
+	UnprocessableEntityError,
+	RateLimitError,
+	InternalServerError,
+} from "./errors.js";

package/src/_utils/resource.ts

@@ -0,0 +1,9 @@
+import type { BaseClient } from "./client.js";
+
+export class APIResource {
+	protected _client: BaseClient;
+
+	constructor(client: BaseClient) {
+		this._client = client;
+	}
+}

package/src/_utils/sse.ts

@@ -0,0 +1,72 @@
+/**
+ * SSE line-stream parser.
+ * Converts a ReadableStream of text chunks into parsed JSON event objects.
+ */
+
+import { SSEParseError } from "./errors.js";
+
+const DATA_PREFIX = "data:";
+
+/** Split a ReadableStream<string> of arbitrary text chunks into lines. */
+async function* splitLines(stream: ReadableStream<string>): AsyncGenerator<string> {
+	const reader = stream.getReader();
+	let buffer = "";
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			buffer += value;
+			const lines = buffer.split("\n");
+			// Last element is either empty (if chunk ended with \n) or a partial line
+			buffer = lines.pop() ?? "";
+
+			for (const line of lines) {
+				yield line;
+			}
+		}
+
+		// Flush any remaining partial line
+		if (buffer.length > 0) {
+			yield buffer;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+/**
+ * Parse an SSE text stream into JSON event objects.
+ *
+ * Mirrors Python SDK's `parse_sse_line_stream`:
+ * - Strips each line
+ * - Skips empty lines and comment lines (`:` prefix)
+ * - Extracts `data:` payloads and parses as JSON
+ * - Ignores `event:`, `id:`, `retry:` lines
+ */
+export async function* parseSSEStream(
+	stream: ReadableStream<string>,
+): AsyncGenerator<Record<string, unknown>> {
+	for await (const rawLine of splitLines(stream)) {
+		const line = rawLine.trim();
+
+		// Skip empty lines and comments
+		if (!line || line.startsWith(":")) {
+			continue;
+		}
+
+		// Parse data lines
+		if (line.startsWith(DATA_PREFIX)) {
+			const dataStr = line.slice(DATA_PREFIX.length).trim();
+
+			try {
+				yield JSON.parse(dataStr) as Record<string, unknown>;
+			} catch {
+				throw new SSEParseError("Malformed JSON in SSE event", line);
+			}
+		}
+
+		// Ignore event:, id:, retry: lines
+	}
+}