@tiny-fish/sdk 0.0.1 → 0.0.3

package/src/_utils/client.ts

@@ -1,219 +0,0 @@
-/**
- * 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

@@ -1,153 +0,0 @@
-/**
- * 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

@@ -1,31 +0,0 @@
-/**
- * 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

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

package/src/_utils/sse.ts

@@ -1,72 +0,0 @@
-/**
- * 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
-	}
-}

package/src/agent/index.ts

@@ -1,210 +0,0 @@
-/**
- * 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());
-	}
-}