@tiny-fish/sdk 0.0.1

package/src/agent/index.ts

@@ -0,0 +1,210 @@
+/**
+ * Browser automation resource.
+ */
+
+import { APIResource } from "../_utils/resource.js";
+import { parseSSEStream } from "../_utils/sse.js";
+import type {
+	AgentRunAsyncResponse,
+	AgentRunParams,
+	AgentRunResponse,
+	AgentRunWithStreamingResponse,
+	BrowserProfile,
+	CompleteEvent,
+	HeartbeatEvent,
+	ProgressEvent,
+	ProxyConfig,
+	RunError,
+	RunStatus,
+	StartedEvent,
+	StreamOptions,
+	StreamingUrlEvent,
+} from "./types.js";
+
+/** JSON body sent to automation endpoints. */
+interface AgentRunBody {
+	goal: string;
+	url: string;
+	browser_profile?: BrowserProfile;
+	proxy_config?: ProxyConfig;
+}
+
+/**
+ * Build the JSON request body from typed params.
+ * Optional fields are omitted rather than sent as undefined/null.
+ */
+function buildRunBody(params: AgentRunParams): AgentRunBody {
+	const body: AgentRunBody = { goal: params.goal, url: params.url };
+	if (params.browser_profile !== undefined) body.browser_profile = params.browser_profile;
+	if (params.proxy_config !== undefined) body.proxy_config = params.proxy_config;
+	return body;
+}
+
+/** Async-iterable wrapper around an SSE event stream, this is what we return when they call the stream endpoint */
+export class AgentStream {
+	private _generator: AsyncGenerator<AgentRunWithStreamingResponse>;
+
+	constructor(generator: AsyncGenerator<AgentRunWithStreamingResponse>) {
+		this._generator = generator;
+	}
+
+	[Symbol.asyncIterator](): AsyncGenerator<AgentRunWithStreamingResponse> {
+		return this._generator;
+	}
+
+	/** Abort the underlying stream. */
+	async close(): Promise<void> {
+		await this._generator.return(undefined);
+	}
+}
+
+/** Validate raw SSE data into a typed event. Returns null for malformed or unknown events. */
+function validateEvent(data: Record<string, unknown>): AgentRunWithStreamingResponse | null {
+	const type = data["type"];
+	if (typeof type !== "string") return null;
+
+	switch (type) {
+		case "STARTED": {
+			if (typeof data["runId"] !== "string" || typeof data["timestamp"] !== "string") return null;
+			return { type: "STARTED", runId: data["runId"], timestamp: data["timestamp"] };
+		}
+		case "STREAMING_URL": {
+			if (
+				typeof data["runId"] !== "string" ||
+				typeof data["streamingUrl"] !== "string" ||
+				typeof data["timestamp"] !== "string"
+			)
+				return null;
+			return {
+				type: "STREAMING_URL",
+				runId: data["runId"],
+				streamingUrl: data["streamingUrl"],
+				timestamp: data["timestamp"],
+			};
+		}
+		case "PROGRESS": {
+			if (
+				typeof data["runId"] !== "string" ||
+				typeof data["purpose"] !== "string" ||
+				typeof data["timestamp"] !== "string"
+			)
+				return null;
+			return {
+				type: "PROGRESS",
+				runId: data["runId"],
+				purpose: data["purpose"],
+				timestamp: data["timestamp"],
+			};
+		}
+		case "HEARTBEAT": {
+			if (typeof data["timestamp"] !== "string") return null;
+			return { type: "HEARTBEAT", timestamp: data["timestamp"] };
+		}
+		case "COMPLETE": {
+			if (
+				typeof data["runId"] !== "string" ||
+				typeof data["status"] !== "string" ||
+				typeof data["timestamp"] !== "string"
+			)
+				return null;
+			return {
+				type: "COMPLETE",
+				runId: data["runId"],
+				status: data["status"] as RunStatus,
+				timestamp: data["timestamp"],
+				resultJson: (data["resultJson"] as Record<string, unknown> | null) ?? null,
+				error: (data["error"] as RunError | null) ?? null,
+			};
+		}
+		default:
+			return null;
+	}
+}
+
+/** Validate raw event data, fire the matching callback, and return the typed event. */
+function dispatchEvent(
+	data: Record<string, unknown>,
+	options: StreamOptions,
+): AgentRunWithStreamingResponse | null {
+	const event = validateEvent(data);
+	if (!event) return null;
+
+	switch (event.type) {
+		case "STARTED":
+			options.onStarted?.(event);
+			break;
+		case "STREAMING_URL":
+			options.onStreamingUrl?.(event);
+			break;
+		case "PROGRESS":
+			options.onProgress?.(event);
+			break;
+		case "HEARTBEAT":
+			options.onHeartbeat?.(event);
+			break;
+		case "COMPLETE":
+			options.onComplete?.(event);
+			break;
+	}
+
+	return event;
+}
+
+/** Browser automation methods. */
+export class AgentResource extends APIResource {
+	/**
+	 * Run a browser automation.
+	 *
+	 * Returns a promise that resolves with the completed agent run output.
+	 */
+	async run(params: AgentRunParams): Promise<AgentRunResponse> {
+		return this._client.post<AgentRunResponse>("/v1/automation/run", {
+			json: buildRunBody(params),
+		});
+	}
+
+	/**
+	 * Queue a browser automation and return immediately.
+	 *
+	 * Does not wait for the run to complete — returns a `run_id` straight away.
+	 * Use `client.runs.get(run_id)` to poll for the result.
+	 */
+	async queue(params: AgentRunParams): Promise<AgentRunAsyncResponse> {
+		return this._client.post<AgentRunAsyncResponse>("/v1/automation/run-async", {
+			json: buildRunBody(params),
+		});
+	}
+
+	/**
+	 * Stream live events from a browser automation run.
+	 *
+	 * Returns an `AgentStream` that yields typed SSE events in real time:
+	 * STARTED → STREAMING_URL → PROGRESS (repeated) → COMPLETE.
+	 *
+	 * Use the `on*` callbacks for a reactive style, or iterate over
+	 * the stream for a sequential style:
+	 *
+	 * ```ts
+	 * const stream = await client.agent.stream({ goal: "...", url: "..." });
+	 * for await (const event of stream) {
+	 *   if (event.type === "PROGRESS") console.log(event.purpose);
+	 * }
+	 * ```
+	 */
+	async stream(params: AgentRunParams, options: StreamOptions = {}): Promise<AgentStream> {
+		const raw = await this._client.postStream("/v1/automation/run-sse", {
+			json: buildRunBody(params),
+		});
+
+		async function* generate(): AsyncGenerator<AgentRunWithStreamingResponse> {
+			for await (const data of parseSSEStream(raw)) {
+				const event = dispatchEvent(data, options);
+				if (event) {
+					yield event;
+				}
+			}
+		}
+
+		return new AgentStream(generate());
+	}
+}

package/src/agent/types.ts

@@ -0,0 +1,190 @@
+/**
+ * Agent automation request/response types.
+ */
+
+// -- Input types --
+
+/** Browser profile for execution. */
+export enum BrowserProfile {
+	LITE = "lite",
+	STEALTH = "stealth",
+}
+
+/** ISO 3166-1 alpha-2 country code for proxy location. */
+export enum ProxyCountryCode {
+	US = "US",
+	GB = "GB",
+	CA = "CA",
+	DE = "DE",
+	FR = "FR",
+	JP = "JP",
+	AU = "AU",
+}
+
+/** Proxy configuration for browser automation. */
+export interface ProxyConfig {
+	/** Enable proxy for this automation run. */
+	enabled: boolean;
+	/** ISO 3166-1 alpha-2 country code for proxy location. */
+	country_code?: ProxyCountryCode;
+}
+
+/** Parameters for a synchronous agent run. */
+export interface AgentRunParams {
+	/** Natural language description of what to do on the page. */
+	goal: string;
+	/** The URL to open the browser on. */
+	url: string;
+	/** `"lite"` (default) or `"stealth"` (anti-detection). */
+	browser_profile?: BrowserProfile;
+	/** Optional proxy settings. */
+	proxy_config?: ProxyConfig;
+}
+
+// -- Response types (shared with runs later) --
+
+/**
+ * Status of an automation run.
+ *
+ * Use these constants instead of raw strings when filtering or branching
+ * on run status — your IDE will autocomplete the options and typos become
+ * type errors.
+ */
+export enum RunStatus {
+	PENDING = "PENDING",
+	RUNNING = "RUNNING",
+	COMPLETED = "COMPLETED",
+	FAILED = "FAILED",
+	CANCELLED = "CANCELLED",
+}
+
+/**
+ * Error category indicating the source of failure.
+ *
+ * - `SYSTEM_FAILURE` — TinyFish infrastructure issue, safe to retry.
+ * - `AGENT_FAILURE` — Problem with the run itself, fix the input.
+ * - `UNKNOWN` — Unclassified, treat as retryable.
+ */
+export enum ErrorCategory {
+	SYSTEM_FAILURE = "SYSTEM_FAILURE",
+	AGENT_FAILURE = "AGENT_FAILURE",
+	UNKNOWN = "UNKNOWN",
+}
+
+/** Error details for failed runs. */
+export interface RunError {
+	/** Error message describing why the run failed. */
+	message: string;
+	/** Error category indicating the source of failure. */
+	category: ErrorCategory;
+	/** Suggested retry delay in whole seconds (integer). */
+	retry_after: number | null;
+	/** URL to troubleshooting docs. */
+	help_url?: string;
+	/** Human-readable guidance. */
+	help_message?: string;
+}
+
+/**
+ * Response from synchronous automation execution.
+ *
+ * Check `status` to determine success/failure:
+ * - On success: `result` is populated, `error` is `null`.
+ * - On failure: `result` is `null`, `error` contains the message.
+ */
+export interface AgentRunResponse {
+	/** Final status of the automation run. */
+	status: RunStatus;
+	/** Unique identifier for the automation run. */
+	run_id: string | null;
+	/** Structured JSON result extracted from the automation. `null` if the run failed. */
+	result: Record<string, unknown> | null;
+	/** Error details. `null` if the run succeeded. */
+	error: RunError | null;
+	/** Number of steps taken during the automation. */
+	num_of_steps: number;
+	/** ISO 8601 timestamp when the run started. */
+	started_at: string | null;
+	/** ISO 8601 timestamp when the run finished. */
+	finished_at: string | null;
+}
+
+/**
+ * Response from asynchronous automation execution.
+ *
+ * Returns `run_id` immediately without waiting for completion.
+ * Use `client.runs.get(run_id)` to check status later.
+ */
+export interface AgentRunAsyncResponse {
+	/** Unique identifier for the created automation run. */
+	run_id: string | null;
+	/** Error details. `null` if successful. */
+	error: RunError | null;
+}
+
+// -- SSE streaming event types --
+
+/** SSE event type discriminator. */
+export enum EventType {
+	STARTED = "STARTED",
+	STREAMING_URL = "STREAMING_URL",
+	PROGRESS = "PROGRESS",
+	HEARTBEAT = "HEARTBEAT",
+	COMPLETE = "COMPLETE",
+}
+
+/** SSE event indicating the automation run has started. */
+export interface StartedEvent {
+	type: "STARTED";
+	runId: string;
+	timestamp: string;
+}
+
+/** SSE event providing the live browser streaming URL. */
+export interface StreamingUrlEvent {
+	type: "STREAMING_URL";
+	runId: string;
+	streamingUrl: string;
+	timestamp: string;
+}
+
+/** SSE event indicating automation progress/activity. */
+export interface ProgressEvent {
+	type: "PROGRESS";
+	runId: string;
+	purpose: string;
+	timestamp: string;
+}
+
+/** SSE event for connection keepalive. */
+export interface HeartbeatEvent {
+	type: "HEARTBEAT";
+	timestamp: string;
+}
+
+/** SSE event indicating the automation run has completed. */
+export interface CompleteEvent {
+	type: "COMPLETE";
+	runId: string;
+	status: RunStatus;
+	timestamp: string;
+	resultJson: Record<string, unknown> | null;
+	error: RunError | null;
+}
+
+/** Union type for all possible SSE streaming events. */
+export type AgentRunWithStreamingResponse =
+	| StartedEvent
+	| StreamingUrlEvent
+	| ProgressEvent
+	| HeartbeatEvent
+	| CompleteEvent;
+
+/** Optional callbacks for stream events. */
+export interface StreamOptions {
+	onStarted?: (event: StartedEvent) => void;
+	onStreamingUrl?: (event: StreamingUrlEvent) => void;
+	onProgress?: (event: ProgressEvent) => void;
+	onHeartbeat?: (event: HeartbeatEvent) => void;
+	onComplete?: (event: CompleteEvent) => void;
+}

package/src/client.ts

@@ -0,0 +1,19 @@
+/**
+ * TinyFish TypeScript SDK client.
+ */
+
+import { BaseClient } from "./_utils/client.js";
+import type { ClientOptions } from "./_utils/client.js";
+import { AgentResource } from "./agent/index.js";
+import { RunsResource } from "./runs/index.js";
+
+export class TinyFish extends BaseClient {
+	readonly agent: AgentResource;
+	readonly runs: RunsResource;
+
+	constructor(options?: ClientOptions) {
+		super(options);
+		this.agent = new AgentResource(this);
+		this.runs = new RunsResource(this);
+	}
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+/**
+ * TinyFish TypeScript SDK — State-of-the-art web agents in an API.
+ */
+
+export { VERSION } from "./version.js";
+export type { ClientOptions } from "./_utils/client.js";
+
+// Client
+export { TinyFish } from "./client.js";
+
+// Resources
+export { AgentStream } from "./agent/index.js";
+
+// Agent types
+export {
+	BrowserProfile,
+	ProxyCountryCode,
+	RunStatus,
+	ErrorCategory,
+	EventType,
+} from "./agent/types.js";
+export type {
+	ProxyConfig,
+	AgentRunParams,
+	AgentRunResponse,
+	AgentRunAsyncResponse,
+	RunError,
+	StartedEvent,
+	StreamingUrlEvent,
+	ProgressEvent,
+	HeartbeatEvent,
+	CompleteEvent,
+	AgentRunWithStreamingResponse,
+	StreamOptions,
+} from "./agent/types.js";
+
+// Runs types
+export { SortDirection } from "./runs/types.js";
+export type {
+	BrowserConfig,
+	Run,
+	PaginationInfo,
+	RunListResponse,
+	RunListParams,
+} from "./runs/types.js";
+
+// Error hierarchy
+export {
+	SDKError,
+	SSEParseError,
+	APIError,
+	APIConnectionError,
+	APITimeoutError,
+	APIStatusError,
+	BadRequestError,
+	AuthenticationError,
+	PermissionDeniedError,
+	NotFoundError,
+	RequestTimeoutError,
+	ConflictError,
+	UnprocessableEntityError,
+	RateLimitError,
+	InternalServerError,
+} from "./_utils/errors.js";

package/src/runs/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Runs resource for retrieving and listing automation runs.
+ */
+
+import { APIResource } from "../_utils/resource.js";
+import type { Run, RunListParams, RunListResponse } from "./types.js";
+
+/** Retrieve and list automation runs. */
+export class RunsResource extends APIResource {
+	/**
+	 * Retrieve a single run by its ID.
+	 *
+	 * Returns a promise that resolves with the full run details
+	 * including status, result, error, and browser configuration.
+	 *
+	 * @param runId - The run ID returned by `agent.queue()` or any run response.
+	 */
+	async get(runId: string): Promise<Run> {
+		if (typeof runId !== "string" || !runId.trim()) {
+			throw new Error("run_id must be a non-empty string");
+		}
+		return this._client.get<Run>(`/v1/runs/${encodeURIComponent(runId)}`);
+	}
+
+	/**
+	 * List automation runs, with optional filtering and pagination.
+	 *
+	 * Returns a promise that resolves with a paginated list of runs
+	 * and pagination info (total count, next cursor).
+	 */
+	async list(params: RunListParams = {}): Promise<RunListResponse> {
+		const queryParams: Record<string, string | number | boolean> = {};
+		if (params.cursor !== undefined) queryParams["cursor"] = params.cursor;
+		if (params.limit !== undefined) queryParams["limit"] = params.limit;
+		if (params.status !== undefined) queryParams["status"] = params.status;
+		if (params.goal !== undefined) queryParams["goal"] = params.goal;
+		if (params.created_after !== undefined) queryParams["created_after"] = params.created_after;
+		if (params.created_before !== undefined) queryParams["created_before"] = params.created_before;
+		if (params.sort_direction !== undefined) queryParams["sort_direction"] = params.sort_direction;
+
+		const hasParams = Object.keys(queryParams).length > 0;
+		return this._client.get<RunListResponse>(
+			"/v1/runs",
+			hasParams ? { params: queryParams } : undefined,
+		);
+	}
+}

package/src/runs/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Runs management request/response types.
+ */
+
+import type { RunError, RunStatus } from "../agent/types.js";
+
+/** Sort order for list queries. */
+export 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;
+}

package/src/version.ts

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