@tiny-fish/sdk 0.0.1 → 0.0.3

package/src/agent/types.ts

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

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

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

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

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

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