@gaiventures/pilotfish 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +182 -2
- package/dist/client.d.ts +272 -0
- package/dist/client.js +385 -0
- package/dist/errors.d.ts +58 -0
- package/dist/errors.js +89 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +8 -0
- package/dist/local.d.ts +161 -0
- package/dist/local.js +274 -0
- package/dist/types.d.ts +334 -0
- package/dist/types.js +2 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +2 -0
- package/dist/webhooks.d.ts +23 -0
- package/dist/webhooks.js +44 -0
- package/package.json +52 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 gAI Ventures
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,183 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pilotfish SDK for TypeScript and JavaScript
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Browser tasks from code, two ways, with the same names in TypeScript and [Python](https://github.com/gAI-ventures/pilotfish-ai/tree/main/sdks/python):
|
|
4
|
+
|
|
5
|
+
- **Hosted** (`Pilotfish`): send a whole web task to pilotfish's cloud browser and get the answer back. pilotfish
|
|
6
|
+
plans it, signs in with your saved logins, clears bot checks, and checks the result before it says done. Paid from
|
|
7
|
+
your organization's credits.
|
|
8
|
+
- **Local** (`LocalBrowser`): drive Chrome on your own machine from your code, through the open MCP's browser tools.
|
|
9
|
+
No account, no API key, no model calls: your code decides each step.
|
|
10
|
+
|
|
11
|
+
Both send pages as compact outlines and, after the first look, only what changed, so an agent reading them spends far
|
|
12
|
+
fewer tokens and each step comes back sooner.
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
npm install @gaiventures/pilotfish
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Node.js 20.3 or later. Docs: <https://pilotfish.gai.ventures/docs/sdk> · REST API: <https://pilotfish.gai.ventures/docs/api>
|
|
19
|
+
|
|
20
|
+
## Hosted: tasks in pilotfish's cloud
|
|
21
|
+
|
|
22
|
+
Make an API key in the app (Org settings → API keys) and set `PILOTFISH_API_KEY`, or pass `apiKey`.
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { Pilotfish } from "@gaiventures/pilotfish";
|
|
26
|
+
|
|
27
|
+
const pf = new Pilotfish(); // reads PILOTFISH_API_KEY
|
|
28
|
+
|
|
29
|
+
const task = await pf.tasks.run({
|
|
30
|
+
task: "Find the cheapest non-stop flight from Delhi to Mumbai on 12 December and report the airline, times and fare",
|
|
31
|
+
startUrl: "https://www.google.com/travel/flights",
|
|
32
|
+
});
|
|
33
|
+
console.log(task.status, task.result?.result);
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`tasks.run` starts the task and waits until it ends, or until it waits on a question for the person
|
|
37
|
+
(`status: "needs_input"`; pass `returnOnQuestion: false` to wait through questions). `tasks.create` returns at once with
|
|
38
|
+
the task's `id`, `url`, `appUrl` (watch it in the app) and `answerUrl` (where a person answers what it asks).
|
|
39
|
+
|
|
40
|
+
### Steer, answer, follow up
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
const t = await pf.tasks.create("Book a table for two at 8 pm tomorrow at Olive, Bandra");
|
|
44
|
+
for await (const event of pf.tasks.stream(t.id)) console.log(event.type); // each event once, until it ends
|
|
45
|
+
|
|
46
|
+
await pf.tasks.message(t.id, "make it 8:30 instead"); // read before its next step
|
|
47
|
+
const waiting = await pf.tasks.wait(t.id);
|
|
48
|
+
if (waiting.question) await pf.tasks.answer(t.id, waiting.question.id, "yes");
|
|
49
|
+
// Codes and passwords are never sent through the API: the person enters them on waiting.answerUrl.
|
|
50
|
+
|
|
51
|
+
const next = await pf.tasks.followUp(t.id, "now add a note: window seat"); // same browser, same sign-ins
|
|
52
|
+
const paused = await pf.tasks.get(next.id);
|
|
53
|
+
if (paused.paused && paused.next === "continue") await pf.tasks.continue(next.id);
|
|
54
|
+
await pf.tasks.cancel(next.id);
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Also: `get`, `list` (one page) and `iterate` (all pages), `events`, `pause` / `resume` (take the browser and hand it
|
|
58
|
+
back), `rerun`, `thread` (the whole session), `files` and `downloadFile`, `frames`, `replayMp4`, `deleteSession`.
|
|
59
|
+
|
|
60
|
+
### Structured output
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
const t = await pf.tasks.run({
|
|
64
|
+
task: "Price and stock of the Logitech MX Master 3S on amazon.in",
|
|
65
|
+
outputSchema: { type: "object", properties: { price: { type: "number" }, inStock: { type: "boolean" } }, required: ["price", "inStock"] },
|
|
66
|
+
});
|
|
67
|
+
t.result?.data; // { price: 8995, inStock: true } when it validates
|
|
68
|
+
t.result?.dataError; // else why not: { code: "schema_mismatch" | "no_answer", errors }
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Batches: many tasks, one request
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
const batch = await pf.batches.run({
|
|
75
|
+
name: "Prices",
|
|
76
|
+
tasks: ["Price of the MX Master 3S on amazon.in", "Price of the MX Master 3S on flipkart.com", { task: "Price on croma.com", region: "in" }],
|
|
77
|
+
defaults: { maxSteps: 40 },
|
|
78
|
+
webhookUrl: "https://example.com/hooks/pilotfish", // batch.finished, signed
|
|
79
|
+
});
|
|
80
|
+
for (const item of batch.items ?? []) console.log(item.status, item.result?.result, item.costUsd);
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Up to 100 tasks run one after another under the one-task-at-a-time rule, and their results are collected together.
|
|
84
|
+
Each task is charged when it runs; if credits run out, the rest are skipped, never run or charged. `batches.create`,
|
|
85
|
+
`get`, `wait`, `list` and `cancel` (the running task is cancelled, the rest skipped).
|
|
86
|
+
|
|
87
|
+
### Identities: tasks for your own users
|
|
88
|
+
|
|
89
|
+
With an org API key (it works in a shared project), each of your end users is an identity with their own logins,
|
|
90
|
+
sessions, IP address and device:
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
const user = await pf.identities.create({ externalUserId: "user-42", label: "Ada" });
|
|
94
|
+
const link = await pf.identities.loginLink(user.id, { sites: ["linkedin.com"] }); // they type their own login there
|
|
95
|
+
await pf.tasks.run({ task: "List my 5 newest LinkedIn messages", identity: user.id });
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Also `get`, `list`, `update`, `delete`, `usage`, `addCredential` (from your own server), `credentials`,
|
|
99
|
+
`setDefaultCredential`, `deleteCredential`.
|
|
100
|
+
|
|
101
|
+
### Saved tasks, schedules, usage
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
const saved = await pf.savedTasks.create({ name: "Daily fares", task: "Cheapest DEL-BOM fare tomorrow", options: { model: "gpt-6-luna" } });
|
|
105
|
+
await pf.schedules.create({ savedTaskId: saved.id, rule: { repeat: "daily", time: "08:00", tz: "Asia/Kolkata" } });
|
|
106
|
+
await pf.savedTasks.run(saved.id, { extraInstructions: "only non-stop" });
|
|
107
|
+
const usage = await pf.usage.get({ days: 30 });
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Saved tasks and schedules live in your Personal project (a person's own key); an org key's shared project answers
|
|
111
|
+
`409 shared_project`.
|
|
112
|
+
|
|
113
|
+
### Errors and retries
|
|
114
|
+
|
|
115
|
+
Every error is the API's `{error, code, hint, docs, fields, retryAfterS}` as an exception: `BadRequestError` (400,
|
|
116
|
+
with `fields`), `AuthenticationError` (401), `PaymentRequiredError` (402: `no_credits`, `allocation_used`,
|
|
117
|
+
`org_limit`), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409: `one_session`,
|
|
118
|
+
`identity_busy`), `RateLimitError` (429, with `retryAfterS`), `ServerError` (5xx), `ConnectionError`, and
|
|
119
|
+
`WaitTimeoutError` from `wait` (the task carries on). All extend `PilotfishError`.
|
|
120
|
+
|
|
121
|
+
A 429 is retried after its `retryAfterS` (it refused before anything was made, so a POST is safe to send again); a 5xx
|
|
122
|
+
or a network failure is retried for reads only. `maxRetries` (default 2), `timeoutMs` (default 60 s per request).
|
|
123
|
+
|
|
124
|
+
### Webhooks
|
|
125
|
+
|
|
126
|
+
`job.needs_input`, `job.finished`, `job.question_withdrawn`, `identity.login_saved` and `batch.finished` are signed
|
|
127
|
+
with your org's webhook secret (Org settings):
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
import { parseWebhook } from "@gaiventures/pilotfish";
|
|
131
|
+
|
|
132
|
+
const event = await parseWebhook(process.env.PILOTFISH_WEBHOOK_SECRET!, req.headers["pilotfish-signature"], rawBody);
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`verifyWebhook` returns true or false instead; both refuse a signature over 5 minutes old. Pass the raw body as
|
|
136
|
+
received, before any JSON parsing.
|
|
137
|
+
|
|
138
|
+
## Local: Chrome on your machine
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
import { LocalBrowser } from "@gaiventures/pilotfish";
|
|
142
|
+
|
|
143
|
+
const browser = await LocalBrowser.start({ headless: false });
|
|
144
|
+
await browser.navigate("https://news.ycombinator.com");
|
|
145
|
+
const titles = await browser.query<string[]>("[...document.querySelectorAll('.titleline > a')].slice(0, 5).map((a) => a.textContent)");
|
|
146
|
+
console.log(titles.value);
|
|
147
|
+
const page = await browser.snapshot(); // the page as an outline with refs: [e12]<a>new
|
|
148
|
+
await browser.click("e12");
|
|
149
|
+
await browser.close();
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
It starts the open MCP ([`@gaiventures/pilotfish-mcp`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp))
|
|
153
|
+
and talks to it over stdio: the installed package when there is one (`npm install @gaiventures/pilotfish-mcp` to pin
|
|
154
|
+
it), else `npx -y @gaiventures/pilotfish-mcp`. Every browser tool is a method: `navigate`, `snapshot`, `click`,
|
|
155
|
+
`type`, `select`, `press`, `scroll`, `actions` (up to 10 steps in one call), `query`, `find`, `getText`,
|
|
156
|
+
`screenshot`, `wait`, `resume`, `tabs`, `pageTool`, plus `call(name, args)` for any tool by name and `close`. Each
|
|
157
|
+
returns `{text, images, structured, isError}`; a tool's error is thrown as `LocalToolError` (`throwOnError: false`
|
|
158
|
+
returns it instead).
|
|
159
|
+
|
|
160
|
+
Options: `headless`, `allowedHosts`, `allowPrivate` (localhost, for testing your own app), `secrets` (typed as
|
|
161
|
+
`{{name}}`, never in any result), `chrome`, `env` (any of the MCP's settings), `command`, `timeoutMs`.
|
|
162
|
+
|
|
163
|
+
A step that looks irreversible (pay, place an order, send, delete) needs a yes, and a page that needs a person (a
|
|
164
|
+
sign-in, a code, a CAPTCHA) is theirs to handle in the window. Pass `onQuestion` to answer:
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
const browser = await LocalBrowser.start({
|
|
168
|
+
onQuestion: async ({ kind, message }) => (kind === "confirm" ? await askTheUser(message) : await waitUntilDone(message)),
|
|
169
|
+
});
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Without it, an irreversible step is refused, and a page that needs a person says `NEEDS A PERSON` in the result (call
|
|
173
|
+
`resume()` once it is handled).
|
|
174
|
+
|
|
175
|
+
## Links
|
|
176
|
+
|
|
177
|
+
- Docs: <https://pilotfish.gai.ventures/docs/sdk> · REST API reference: <https://pilotfish.gai.ventures/docs/api>
|
|
178
|
+
- Source: [gAI-ventures/pilotfish-ai](https://github.com/gAI-ventures/pilotfish-ai/tree/main/packages/sdk) on GitHub.
|
|
179
|
+
Issues: <https://github.com/gAI-ventures/pilotfish-ai/issues>.
|
|
180
|
+
|
|
181
|
+
## License
|
|
182
|
+
|
|
183
|
+
MIT
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
import type { Answer, Batch, BatchRequest, CredentialCreate, FollowUpRequest, Identity, IdentityCreate, LoginLink, Page, SavedTask, SavedTaskOptions, Schedule, ScheduleRule, SessionFile, Task, TaskEvent, TaskRequest, TaskStatus, Usage } from "./types.js";
|
|
2
|
+
export declare const DEFAULT_BASE_URL = "https://pilotfish-be.gai.ventures";
|
|
3
|
+
/** The text the app sends to carry a paused task on. */
|
|
4
|
+
export declare const CONTINUE_TEXT = "Continue the task from where you left off.";
|
|
5
|
+
export interface ClientOptions {
|
|
6
|
+
/** An API key (`pf_…`, Org settings → API keys). Default: the `PILOTFISH_API_KEY` environment variable. */
|
|
7
|
+
apiKey?: string;
|
|
8
|
+
/** Default: `PILOTFISH_BASE_URL`, else https://pilotfish-be.gai.ventures. */
|
|
9
|
+
baseUrl?: string;
|
|
10
|
+
/** Tries after the first for a 429 (after its `retryAfterS`), a 5xx or a network failure on a read. Default 2. */
|
|
11
|
+
maxRetries?: number;
|
|
12
|
+
/** Per-request timeout, ms. Default 60 s. */
|
|
13
|
+
timeoutMs?: number;
|
|
14
|
+
/** Your own fetch (tests, proxies). */
|
|
15
|
+
fetch?: typeof fetch;
|
|
16
|
+
}
|
|
17
|
+
export interface WaitOptions {
|
|
18
|
+
/** Give up waiting after this long, ms (the task carries on). Default 30 min. */
|
|
19
|
+
timeoutMs?: number;
|
|
20
|
+
/** How often to look, ms. Default 2 s. */
|
|
21
|
+
pollMs?: number;
|
|
22
|
+
/** Also return when the task waits on a question (status `needs_input`). Default true. */
|
|
23
|
+
returnOnQuestion?: boolean;
|
|
24
|
+
signal?: AbortSignal;
|
|
25
|
+
}
|
|
26
|
+
type Query = Record<string, string | number | boolean | undefined>;
|
|
27
|
+
export declare class Pilotfish {
|
|
28
|
+
readonly baseUrl: string;
|
|
29
|
+
private readonly apiKey;
|
|
30
|
+
private readonly maxRetries;
|
|
31
|
+
private readonly timeoutMs;
|
|
32
|
+
private readonly fetchImpl;
|
|
33
|
+
readonly tasks: Tasks;
|
|
34
|
+
readonly batches: Batches;
|
|
35
|
+
readonly identities: Identities;
|
|
36
|
+
readonly savedTasks: SavedTasks;
|
|
37
|
+
readonly schedules: Schedules;
|
|
38
|
+
readonly usage: UsageApi;
|
|
39
|
+
constructor(o?: ClientOptions);
|
|
40
|
+
/** One API call: JSON in and out, typed errors, retries on 429 (after its `retryAfterS`) and, for reads, on 5xx and network failures. */
|
|
41
|
+
request<T>(method: string, path: string, o?: {
|
|
42
|
+
body?: unknown;
|
|
43
|
+
query?: Query;
|
|
44
|
+
raw?: boolean;
|
|
45
|
+
signal?: AbortSignal;
|
|
46
|
+
}): Promise<T>;
|
|
47
|
+
/** The raw response of a call that returns a file (its bytes). */
|
|
48
|
+
download(path: string, signal?: AbortSignal): Promise<{
|
|
49
|
+
data: Uint8Array;
|
|
50
|
+
contentType: string;
|
|
51
|
+
filename: string | null;
|
|
52
|
+
}>;
|
|
53
|
+
private send;
|
|
54
|
+
}
|
|
55
|
+
/** Tasks (the API's jobs): run, watch, answer, steer, follow up, and read their files and replays. */
|
|
56
|
+
export declare class Tasks {
|
|
57
|
+
private readonly c;
|
|
58
|
+
constructor(c: Pilotfish);
|
|
59
|
+
/** Start a task; returns at once with its id (and `url`, `appUrl`, `answerUrl`). */
|
|
60
|
+
create(req: TaskRequest | string): Promise<Task>;
|
|
61
|
+
/** Start a task and wait for it to end (or to wait on a question, unless `returnOnQuestion: false`). */
|
|
62
|
+
run(req: TaskRequest | string, o?: WaitOptions): Promise<Task>;
|
|
63
|
+
/** A task with its result, question, settings, cost so far and live view. */
|
|
64
|
+
get(id: string): Promise<Task>;
|
|
65
|
+
/** Wait until the task ends, or waits on a question (unless `returnOnQuestion: false`). Throws WaitTimeoutError after `timeoutMs`. */
|
|
66
|
+
wait(id: string, o?: WaitOptions): Promise<Task>;
|
|
67
|
+
/** Your tasks, newest first (a key: the tasks it started). One page; `iterate` walks them all. */
|
|
68
|
+
list(o?: {
|
|
69
|
+
status?: TaskStatus;
|
|
70
|
+
limit?: number;
|
|
71
|
+
cursor?: string;
|
|
72
|
+
project?: string;
|
|
73
|
+
identity?: string;
|
|
74
|
+
}): Promise<Page<Task>>;
|
|
75
|
+
/** Every task, page after page. */
|
|
76
|
+
iterate(o?: {
|
|
77
|
+
status?: TaskStatus;
|
|
78
|
+
limit?: number;
|
|
79
|
+
project?: string;
|
|
80
|
+
identity?: string;
|
|
81
|
+
}): AsyncGenerator<Task>;
|
|
82
|
+
/** The task's events (steps, questions, files…), or those after `after` (an event's `seq`). */
|
|
83
|
+
events(id: string, after?: number): Promise<TaskEvent[]>;
|
|
84
|
+
/** Each new event as it happens, until the task ends. */
|
|
85
|
+
stream(id: string, o?: {
|
|
86
|
+
pollMs?: number;
|
|
87
|
+
signal?: AbortSignal;
|
|
88
|
+
}): AsyncGenerator<TaskEvent>;
|
|
89
|
+
/** The next instruction in the same session: the same browser while it is kept, the same sign-ins, what earlier turns found. */
|
|
90
|
+
followUp(id: string, req: FollowUpRequest | string): Promise<Task>;
|
|
91
|
+
/** Carry a paused task on (`paused: true`, `next: "continue"`), as the app's Continue does. */
|
|
92
|
+
continue(id: string): Promise<Task>;
|
|
93
|
+
/** Answer the task's open question (`task.question.id`). Codes and passwords go on its `answerUrl`, never here. */
|
|
94
|
+
answer(id: string, questionId: string, answer: Answer | "yes" | "no" | "done" | "cancel" | "skip" | (string & {})): Promise<void>;
|
|
95
|
+
/** Tell a running task something in the person's words; it reads it before its next step. */
|
|
96
|
+
message(id: string, text: string): Promise<void>;
|
|
97
|
+
/** Stop a task for good (what it spent stays charged). */
|
|
98
|
+
cancel(id: string): Promise<void>;
|
|
99
|
+
/** Take control: the agent stops at its next turn and the browser is the person's (the live view's control token). */
|
|
100
|
+
pause(id: string): Promise<{
|
|
101
|
+
ok: true;
|
|
102
|
+
control: string;
|
|
103
|
+
}>;
|
|
104
|
+
/** Hand the browser back: the agent carries on from where the person left it. */
|
|
105
|
+
resume(id: string): Promise<{
|
|
106
|
+
ok: true;
|
|
107
|
+
control: string;
|
|
108
|
+
}>;
|
|
109
|
+
/** The same task again with the same settings, as a new task in a new session. */
|
|
110
|
+
rerun(id: string): Promise<Task>;
|
|
111
|
+
/** The task's whole session: its turns with their events, its files, and the browser kept for a follow-up. */
|
|
112
|
+
thread(id: string): Promise<{
|
|
113
|
+
threadId: string;
|
|
114
|
+
jobs: Array<Task & {
|
|
115
|
+
events: TaskEvent[];
|
|
116
|
+
}>;
|
|
117
|
+
files: SessionFile[];
|
|
118
|
+
kept?: unknown;
|
|
119
|
+
}>;
|
|
120
|
+
/** The session's files: attached, downloaded by the run, or PDFs it read. */
|
|
121
|
+
files(id: string, o?: {
|
|
122
|
+
offset?: number;
|
|
123
|
+
limit?: number;
|
|
124
|
+
}): Promise<{
|
|
125
|
+
files: SessionFile[];
|
|
126
|
+
total: number;
|
|
127
|
+
}>;
|
|
128
|
+
/** One file's bytes, with its name and type. */
|
|
129
|
+
downloadFile(id: string, fileId: string): Promise<{
|
|
130
|
+
data: Uint8Array;
|
|
131
|
+
contentType: string;
|
|
132
|
+
filename: string | null;
|
|
133
|
+
}>;
|
|
134
|
+
/** The screenshots taken after the steps that changed the page. */
|
|
135
|
+
frames(id: string): Promise<Array<{
|
|
136
|
+
seq: number;
|
|
137
|
+
at: number;
|
|
138
|
+
step?: number;
|
|
139
|
+
label: string;
|
|
140
|
+
url: string;
|
|
141
|
+
}>>;
|
|
142
|
+
/** The replay video (MP4), while it is kept (7 days by default). */
|
|
143
|
+
replayMp4(id: string): Promise<{
|
|
144
|
+
data: Uint8Array;
|
|
145
|
+
contentType: string;
|
|
146
|
+
filename: string | null;
|
|
147
|
+
}>;
|
|
148
|
+
/** Delete the task's session from history (soft: its record and cost are kept for billing). */
|
|
149
|
+
deleteSession(id: string): Promise<void>;
|
|
150
|
+
}
|
|
151
|
+
/** Batches: many tasks in one request, run one after another, their results collected together. */
|
|
152
|
+
export declare class Batches {
|
|
153
|
+
private readonly c;
|
|
154
|
+
constructor(c: Pilotfish);
|
|
155
|
+
/** Start a batch (up to 100 tasks). Each task is charged when it runs; if credits run out the rest are skipped. */
|
|
156
|
+
create(req: BatchRequest | Array<string | TaskRequest>): Promise<Batch>;
|
|
157
|
+
/** Start a batch and wait for every task to end. */
|
|
158
|
+
run(req: BatchRequest | Array<string | TaskRequest>, o?: Omit<WaitOptions, "returnOnQuestion">): Promise<Batch>;
|
|
159
|
+
/** A batch with each task's status, job id, cost and result. */
|
|
160
|
+
get(id: string): Promise<Batch>;
|
|
161
|
+
/** Wait until the batch ends (done, cancelled or stopped). Throws WaitTimeoutError after `timeoutMs` (default 2 h). */
|
|
162
|
+
wait(id: string, o?: Omit<WaitOptions, "returnOnQuestion">): Promise<Batch>;
|
|
163
|
+
/** Your batches, newest first (without their items). */
|
|
164
|
+
list(o?: {
|
|
165
|
+
status?: Batch["status"];
|
|
166
|
+
limit?: number;
|
|
167
|
+
cursor?: string;
|
|
168
|
+
}): Promise<Page<Batch>>;
|
|
169
|
+
/** Cancel: the running task is cancelled and the rest are skipped (never run, never charged). */
|
|
170
|
+
cancel(id: string): Promise<Batch>;
|
|
171
|
+
}
|
|
172
|
+
/** Identities: your product's end users in a shared project (an org key's project), each with their own logins, sessions, IP and device. */
|
|
173
|
+
export declare class Identities {
|
|
174
|
+
private readonly c;
|
|
175
|
+
constructor(c: Pilotfish);
|
|
176
|
+
/** Make one; with an `externalUserId` you already used, you get that one back (`existed: true`). */
|
|
177
|
+
create(o?: IdentityCreate): Promise<Identity>;
|
|
178
|
+
get(id: string): Promise<Identity>;
|
|
179
|
+
list(o?: {
|
|
180
|
+
externalUserId?: string;
|
|
181
|
+
q?: string;
|
|
182
|
+
limit?: number;
|
|
183
|
+
cursor?: string;
|
|
184
|
+
}): Promise<Page<Identity> & {
|
|
185
|
+
total: number;
|
|
186
|
+
}>;
|
|
187
|
+
update(id: string, o: Partial<IdentityCreate>): Promise<Identity>;
|
|
188
|
+
/** Wipes its logins, sessions and device; its tasks and their cost are kept. */
|
|
189
|
+
delete(id: string): Promise<void>;
|
|
190
|
+
/** What its tasks cost, since `since` (ms since the epoch; default: all of them). */
|
|
191
|
+
usage(id: string, o?: {
|
|
192
|
+
since?: number;
|
|
193
|
+
}): Promise<Usage>;
|
|
194
|
+
/** Save a login for it from your own server (the values are sealed and never read back). */
|
|
195
|
+
addCredential(id: string, o: CredentialCreate): Promise<{
|
|
196
|
+
credential: string;
|
|
197
|
+
identity: string;
|
|
198
|
+
site: string;
|
|
199
|
+
account: string;
|
|
200
|
+
}>;
|
|
201
|
+
credentials(id: string): Promise<NonNullable<Identity["logins"]>>;
|
|
202
|
+
setDefaultCredential(id: string, credential: string): Promise<void>;
|
|
203
|
+
deleteCredential(id: string, credential: string): Promise<void>;
|
|
204
|
+
/** A one-time page where the end user types their own login for these sites. */
|
|
205
|
+
loginLink(id: string, o: {
|
|
206
|
+
sites: string[];
|
|
207
|
+
account?: string;
|
|
208
|
+
ttlMinutes?: number;
|
|
209
|
+
webhookUrl?: string;
|
|
210
|
+
}): Promise<LoginLink>;
|
|
211
|
+
}
|
|
212
|
+
/** Saved tasks (in your Personal project): run again with their settings, by hand or on a schedule. */
|
|
213
|
+
export declare class SavedTasks {
|
|
214
|
+
private readonly c;
|
|
215
|
+
constructor(c: Pilotfish);
|
|
216
|
+
list(): Promise<SavedTask[]>;
|
|
217
|
+
create(o: {
|
|
218
|
+
name: string;
|
|
219
|
+
task: string;
|
|
220
|
+
options?: SavedTaskOptions;
|
|
221
|
+
fromJob?: string;
|
|
222
|
+
}): Promise<SavedTask>;
|
|
223
|
+
update(id: string, o: {
|
|
224
|
+
name?: string;
|
|
225
|
+
task?: string;
|
|
226
|
+
options?: SavedTaskOptions;
|
|
227
|
+
}): Promise<SavedTask>;
|
|
228
|
+
delete(id: string): Promise<void>;
|
|
229
|
+
/** Run it, with changes for this run only. */
|
|
230
|
+
run(id: string, o?: Record<string, unknown> & {
|
|
231
|
+
extraInstructions?: string;
|
|
232
|
+
startUrl?: string | null;
|
|
233
|
+
region?: string | null;
|
|
234
|
+
sites?: string[];
|
|
235
|
+
solve?: boolean;
|
|
236
|
+
outputSchema?: Record<string, unknown> | null;
|
|
237
|
+
}): Promise<Task>;
|
|
238
|
+
}
|
|
239
|
+
/** Schedules: a saved task run by itself. What would stop a run with nobody there is settled first (409 `not_ready`). */
|
|
240
|
+
export declare class Schedules {
|
|
241
|
+
private readonly c;
|
|
242
|
+
constructor(c: Pilotfish);
|
|
243
|
+
list(): Promise<Schedule[]>;
|
|
244
|
+
/** Schedule a saved task (`savedTaskId`), or a new task saved with it (`task`, `name`, `options`). */
|
|
245
|
+
create(o: {
|
|
246
|
+
rule: ScheduleRule;
|
|
247
|
+
savedTaskId?: string;
|
|
248
|
+
name?: string;
|
|
249
|
+
task?: string;
|
|
250
|
+
options?: SavedTaskOptions;
|
|
251
|
+
paused?: boolean;
|
|
252
|
+
}): Promise<Schedule>;
|
|
253
|
+
update(savedTaskId: string, o: {
|
|
254
|
+
rule?: ScheduleRule;
|
|
255
|
+
paused?: boolean;
|
|
256
|
+
name?: string;
|
|
257
|
+
task?: string;
|
|
258
|
+
}): Promise<Schedule>;
|
|
259
|
+
delete(savedTaskId: string): Promise<void>;
|
|
260
|
+
}
|
|
261
|
+
/** Spending: yours (a key: its own), by kind, day, model and task, and what is left of an allowance. */
|
|
262
|
+
export declare class UsageApi {
|
|
263
|
+
private readonly c;
|
|
264
|
+
constructor(c: Pilotfish);
|
|
265
|
+
/** The last `days` (default 30), or `from`/`to` (YYYY-MM-DD). */
|
|
266
|
+
get(o?: {
|
|
267
|
+
days?: number;
|
|
268
|
+
from?: string;
|
|
269
|
+
to?: string;
|
|
270
|
+
}): Promise<Usage>;
|
|
271
|
+
}
|
|
272
|
+
export {};
|