@oya-ai/browser 0.1.0 → 1.0.56
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/README.md +71 -0
- package/package.json +10 -4
package/README.md
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# @oya-ai/browser
|
|
2
|
+
|
|
3
|
+
Thousands of browsers behind one API: personas, proxies, stealth, CAPTCHA and MFA. The browser can run on Oya Cloud, Browserbase, Steel, Anchor, Browser Use, your own machines, or any CDP URL. Which one is a setting on your API key, so your code never changes.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm i @oya-ai/browser
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Get an API key at [browser.getoya.ai](https://browser.getoya.ai) and export it as `OYA_API_KEY`.
|
|
10
|
+
|
|
11
|
+
## Quickstart
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { Oya } from '@oya-ai/browser';
|
|
15
|
+
|
|
16
|
+
const oya = new Oya(); // reads OYA_API_KEY
|
|
17
|
+
await using browser = await oya.browser.start(); // stopped when the block exits, even on error
|
|
18
|
+
await browser.goto('https://news.ycombinator.com');
|
|
19
|
+
console.log(await browser.ask('What are the top 3 stories?'));
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`await using` needs Node 24+ or TypeScript 5.2+. Otherwise call `await browser.stop()` in a `finally` block.
|
|
23
|
+
|
|
24
|
+
## Personas
|
|
25
|
+
|
|
26
|
+
A persona is one device: fingerprint, cookie jar and exit IP, the same on every run.
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
const persona = await oya.personas.create({
|
|
30
|
+
name: 'us-shopper',
|
|
31
|
+
prefs: { platform: 'MacIntel', timezone: 'America/New_York', locale: 'en-US' }, // fixed for life
|
|
32
|
+
proxy: { geo: 'US' },
|
|
33
|
+
});
|
|
34
|
+
await using browser = await oya.browser.start({ persona: persona.id }); // or 'auto' to rotate
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## CAPTCHA and MFA
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
await using browser = await oya.browser.start({ captcha: 'auto' }); // solve on every goto()
|
|
41
|
+
await browser.solveCaptcha(); // or on demand
|
|
42
|
+
|
|
43
|
+
await oya.personas.setMfa(persona.id, { type: 'totp', secret: process.env.TOTP_SECRET! });
|
|
44
|
+
const mfa = await browser.completeMfa(); // totp, email, sms, or a human handoff
|
|
45
|
+
if (!mfa.completed) console.log('Finish it here:', mfa.liveViewUrl);
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Any vendor, any tool
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
import { chromium } from 'playwright-core';
|
|
52
|
+
|
|
53
|
+
await using browser = await oya.browser.start({ provider: 'browserbase' }); // one string per vendor
|
|
54
|
+
const pw = await chromium.connectOverCDP(browser.cdpUrl!); // Playwright, Puppeteer, Stagehand…
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## API
|
|
58
|
+
|
|
59
|
+
| | |
|
|
60
|
+
|---|---|
|
|
61
|
+
| `new Oya({ apiKey?, baseUrl?, timeoutMs? })` | Defaults to `OYA_API_KEY` and `OYA_BASE_URL` |
|
|
62
|
+
| `oya.browser` | `start(options)`, `get(id)`, `list()`, `stop(ids \| 'all')`, `stopAll()` |
|
|
63
|
+
| `browser` | `goto`, `ask`, `analyze`, `elements`, `click`, `type`, `pressKey`, `scroll`, `waitFor`, `screenshot`, `url`, `tabs`, `openTab`, `switchTab`, `closeTab`, `solveCaptcha`, `completeMfa`, `liveViewUrl`, `status`, `stop`, `cdpUrl` |
|
|
64
|
+
| `oya.personas` | `list`, `get`, `create`, `update`, `clone`, `preview`, `options`, `pinProxy`, `remove`, `setMfa`, `clearMfa` |
|
|
65
|
+
| `oya.config` | `get()`, `set(values)`: model, provider and solver keys for this API key |
|
|
66
|
+
| `oya.control` | Sessions, human takeover, events, members, credentials and webhooks |
|
|
67
|
+
| `oya.usage()` | What this key has spent |
|
|
68
|
+
|
|
69
|
+
Errors are thrown as `OyaError` with `status` and `body`. ESM and CommonJS, fully typed, no runtime dependencies, Node 18+.
|
|
70
|
+
|
|
71
|
+
More: [examples](https://github.com/OyadotAI/AgentChrome/tree/main/examples) · [docs](https://browser.getoya.ai/docs) · [CLI](https://www.npmjs.com/package/@oya-ai/cli)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oya-ai/browser",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.0.56",
|
|
4
4
|
"description": "Rotate thousands of browsers behind one API — personas, proxies, stealth, CAPTCHA and MFA.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -14,14 +14,20 @@
|
|
|
14
14
|
"require": "./dist/index.cjs"
|
|
15
15
|
}
|
|
16
16
|
},
|
|
17
|
-
"files": [
|
|
17
|
+
"files": [
|
|
18
|
+
"dist"
|
|
19
|
+
],
|
|
18
20
|
"sideEffects": false,
|
|
19
21
|
"scripts": {
|
|
20
22
|
"build": "tsup src/index.ts --format esm,cjs --dts --clean",
|
|
21
23
|
"prepublishOnly": "npm run build"
|
|
22
24
|
},
|
|
23
|
-
"engines": {
|
|
24
|
-
|
|
25
|
+
"engines": {
|
|
26
|
+
"node": ">=18"
|
|
27
|
+
},
|
|
28
|
+
"publishConfig": {
|
|
29
|
+
"access": "public"
|
|
30
|
+
},
|
|
25
31
|
"devDependencies": {
|
|
26
32
|
"tsup": "^8.0.0",
|
|
27
33
|
"typescript": "^5.4.0"
|