Paprika

https://paps-jp.github.io/paprika/
Admin
Paprika is a browser automation platform that operates Chrome on distributed workers using...
Tokens:24,905
Snippets:209
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example: Run a Session (Sync Python)

Source: https://paps-jp.github.io/paprika/api.html

This example demonstrates how to use the synchronous client to open a session, navigate to a page, and extract information like URL and title.

```python
from paprika_client import sync_paprika

with sync_paprika.connect() as cli:
                      # await 不要
    with cli.session("https://news.ycombinator.com") as page:
        page.locator(".athing .titleline > a").first.click()
        st = page.state()
        print("url:  ", st["url"])
        print("title:", st["title"])
```

--------------------------------

### Install PHP SDK

Source: https://paps-jp.github.io/paprika/api.html

Install the Paprika PHP client using Composer. This command adds the necessary package to your project dependencies.

```bash
composer require paprika/client
```

--------------------------------

### Example: Fetch Job and Collect Images (PHP)

Source: https://paps-jp.github.io/paprika/api.html

This PHP example shows how to initiate a fetch job for a Wikipedia page and then retrieve and display the URLs of all collected images.

```php
<?php
require 'vendor/autoload.php';

use Paprika\Client\Paprika;

$cli = Paprika::connect();   // PAPRIKA_HUB or http://localhost:8000
$job = $cli->fetch('https://en.wikipedia.org/wiki/Cat', scroll: true);
echo "status: {$job['status']}\n";

foreach ($cli->jobImages($job['job_id']) as $u) {
    echo $u, "\n";
}
```

--------------------------------

### Launch Remote Worker for Distributed Setup

Source: https://paps-jp.github.io/paprika/operations.html

Set up and launch a remote worker on a separate machine for a distributed Paprika setup. Ensure the worker's .env file is configured with the Hub's WebSocket URL and its own network details.

```bash
git clone https://github.com/paps-jp/paprika.git /opt/paprika
cd /opt/paprika && cp .env.example .env
# .env を編集:
#   HUB_URL=ws://paprika.lan:8000
#   NOVNC_PUBLIC_HOST=<このホストの LAN IP/DNS>
docker compose -f docker-compose-worker.yml up -d
```

--------------------------------

### Example: Fetch Images in Bulk (Sync Python)

Source: https://paps-jp.github.io/paprika/api.html

Demonstrates fetching all images from a Wikipedia page using a fetch job and then retrieving their URLs.

```python
from paprika_client import sync_paprika

with sync_paprika.connect() as cli:
    job = cli.fetch("https://en.wikipedia.org/wiki/Cat", scroll=True)
    imgs = cli.job_images(job["job_id"])
    print("status:", job["status"])
    print("images:", len(imgs))
    print("first 3:")
    for u in imgs[:3]:
        print(" ", u)
```

--------------------------------

### Example: Open Live Session (PHP)

Source: https://paps-jp.github.io/paprika/api.html

Demonstrates opening a live session to a specified URL using the PHP SDK. It prints the noVNC URL for accessing the session.

```php
use Paprika\Client\Paprika;
use Paprika\Client\Session;

$cli = Paprika::connect();
$cli->session('https://example.com', function (Session $sess) use ($cli) {
    echo "noVNC: ", $cli->baseUrl() . $sess->novncUrl, "\n";
    // Phase 2: $sess->goto(...), $sess->locator(...) ...
});
```

--------------------------------

### Launch Worker via CLI (Development)

Source: https://paps-jp.github.io/paprika/operations.html

Start a Paprika Worker directly from Python for development purposes. This requires a Linux environment with Chrome, Xvfb, and noVNC installed and configured.

```bash
# 別ターミナルで（要: Chrome + Xvfb + noVNC = Linux）
python -m server --mode worker \
  --hub-url ws://localhost:8000 \
  --lane-pool 1 \
  --novnc-public-host localhost --novnc-base-port 6080
```

--------------------------------

### Run a Sequence of Actions

Source: https://paps-jp.github.io/paprika/api.html

Executes a series of actions defined in 'actions' starting from an optional initial URL. Returns a dictionary of results.

```python
await run(actions, *, initial_url=None)
```

--------------------------------

### Connect to Paprika Hub (Async Python)

Source: https://paps-jp.github.io/paprika/api.html

Use this snippet to establish an asynchronous connection to the Paprika Hub. The connection context manager ensures proper setup and teardown.

```python
async with async_paprika.connect() as cli:
    ...
```

--------------------------------

### Get Outline String of a URL

Source: https://paps-jp.github.io/paprika/api.html

Retrieves the outline string for a given URL. Waits for 2 seconds by default.

```python
await outline(url, *, wait=2.0)
```

--------------------------------

### Launch Hub Only via CLI (Development)

Source: https://paps-jp.github.io/paprika/operations.html

Start the Paprika Hub directly from Python without Docker for development and light testing. This command launches a minimal Hub using in-memory storage.

```bash
git clone https://github.com/paps-jp/paprika.git
cd paprika
python -m venv .venv && source .venv/bin/activate   # 任意
pip install -r requirements.txt

# ハブのみ起動（最小・インメモリ）
python -m server --mode hub --host 0.0.0.0 --port 8000
```

--------------------------------

### Configure Hub Host for Distributed Setup

Source: https://paps-jp.github.io/paprika/operations.html

When setting up a distributed Paprika environment, configure the Hub host's .env file to specify public addresses and local worker lanes. This allows remote workers to connect and be managed.

```dotenv
# .env (ハブホスト)
NOVNC_PUBLIC_HOST=paprika.lan            # 管理画面の noVNC リンクが指すホスト名/IP
PUBLIC_BASE_URL=http://paprika.lan:8000  # worker がアセットを POST する先
LANE_POOL=2                              # ローカル worker のレーン数（不要なら 0）
```

--------------------------------

### Get Job Details with curl

Source: https://paps-jp.github.io/paprika/vnc-embed.html

Use curl to POST a job request and retrieve initial job details, including the novnc_url which may initially be null.

```shell
$ curl -s -X POST https://paprika.example.com/jobs \
       -H 'Content-Type: application/json' \
       -d '{"url": "https://example.com",
            "options": {"mode": "fetch", "wait_seconds": 30}}'

{
  "job_id": "a3b4c5d6e7f8",
  "status": "queued",
  "url": "https://example.com",
  "novnc_url": null,                        <-- まだ lane に bind 前
  "worker_id": null,
  "lane_idx": null,
  ...
}
```

--------------------------------

### Get State Information of a URL

Source: https://paps-jp.github.io/paprika/api.html

Fetches state information (like URL and title) for a given URL. Waits for 2 seconds by default.

```python
await state(url, *, wait=2.0)
```

--------------------------------

### Update Paprika Hub

Source: https://paps-jp.github.io/paprika/operations.html

SSH into the Paprika server, navigate to the installation directory, pull the latest changes, and restart the Docker Compose services for the Hub.

```bash
ssh root@paprika.lan
cd /opt/paprika && git pull && docker compose restart hub
```

--------------------------------

### Crawl a Website with walk Helper

Source: https://paps-jp.github.io/paprika/api.html

Performs a website crawl starting from a given URL, saving assets for each visited page. The 'walk' function yields 'Visit' objects containing visit details.

```python
from paprika_client import async_paprika, walk

async with async_paprika.connect() as cli:
    async with cli.session("https://example.com", parent_job_id="crawl") as page:
        async for visit in walk(page, target_pages=50, same_domain=True):
            print(visit.n, visit.depth, visit.url)
            await page.save_assets("out/images")   # 各ページで画像保存など
```

--------------------------------

### Minimal Iframe Embedding Example

Source: https://paps-jp.github.io/paprika/vnc-embed.html

Embed the Paprika worker live screen using a simple iframe tag with the constructed novnc_url as the source. This allows mouse and keyboard interaction.

```html
<iframe
  src="https://paprika.example.com/sessions/ses_abc123def456/novnc/?path=sessions/ses_abc123def456/novnc/websockify&autoconnect=1&resize=scale&reconnect=1"
  width="1024" height="640"
  style="border: 1px solid #444; background: #000;"
  allow="clipboard-read; clipboard-write"
  title="paprika worker live view">
</iframe>
```

--------------------------------

### Execute JavaScript and Get Page Title

Source: https://paps-jp.github.io/paprika/guides.html

Executes JavaScript in the browser context to retrieve the page title.

```javascript
title = await page.evaluate("document.title")
```

--------------------------------

### Embed Paprika Job with JavaScript

Source: https://paps-jp.github.io/paprika/vnc-embed.html

This snippet demonstrates how to start a Paprika job, monitor its lifecycle, and embed the VNC session into an iframe using plain JavaScript. It handles job submission, status polling, and iframe creation.

```javascript
const HUB = 'https://paprika.example.com';

async function embedPaprikaJob(targetUrl, mountEl) {
  // 1) ジョブ投入
  const submit = await fetch(`${HUB}/jobs`, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      url: targetUrl,
      options: { mode: 'fetch', wait_seconds: 30 },
    }),
  });
  const job = await submit.json();
  const jobId = job.job_id;

  // 2) Loading プレースホルダ
  mountEl.innerHTML =
    `<div style="padding:20px;color:#888;">割り当て中... (${jobId})</div>`;

  // 3) novnc_url が立ち上がるまでポーリング (5s 間隔)
  let info = job;
  while (!info.novnc_url) {
    await new Promise(r => setTimeout(r, 5000));
    info = await (await fetch(`${HUB}/jobs/${jobId}`)).json();
    if (['completed','failed','cancelled'].includes(info.status)) {
      mountEl.innerHTML = `<div style="color:#c00;">早期終了: ${info.status}</div>`;
      return;
    }
  }

  // 4) iframe を作って差し込む
  const iframe = document.createElement('iframe');
  iframe.src = HUB + info.novnc_url;
  iframe.style.cssText = 'width:100%; height:100%; border:none; background:#000;';
  iframe.title = `paprika ${jobId}`;
  mountEl.replaceChildren(iframe);

  // 5) 終了監視 — terminal になったら iframe を外す
  const watcher = setInterval(async () => {
    const r = await fetch(`${HUB}/jobs/${jobId}`);
    if (!r.ok) return;
    const cur = await r.json();
    if (['completed','failed','cancelled'].includes(cur.status)) {
      clearInterval(watcher);
      iframe.remove();
      mountEl.innerHTML =
        `<div style="color:#888;">ジョブ終了 (${cur.status})</div>`;
    }
  }, 5000);
}

// 使い方
embedPaprikaJob('https://example.com',
                document.getElementById('vnc-host'));

```

--------------------------------

### Get Job Images (PHP SDK)

Source: https://paps-jp.github.io/paprika/api.html

Retrieves a list of image URLs associated with a completed job.

```APIDOC
## Get Job Images (PHP SDK)

### Description
Retrieves a list of image URLs associated with a completed job.

### Method
`$cli->jobImages(string $jobId)

### Parameters
- **jobId** (string) - Required - The ID of the job.

### Request Example
```php
$images = $cli->jobImages($job['job_id']);
foreach ($images as $url) {
    echo $url, "\n";
}
```

### Response
- **images** (array) - An array of image URLs.
```

--------------------------------

### Maintain Aspect Ratio with iframe

Source: https://paps-jp.github.io/paprika/vnc-embed.html

This example demonstrates how to maintain a specific aspect ratio (16:9) for an embedded iframe using relative positioning and padding. It ensures the VNC display fits within a consistent frame regardless of the iframe's container size.

```html
<div style="position: relative; padding-top: 56.25%;">
  <iframe src="..."
          style="position:absolute; top:0; left:0; width:100%; height:100%; border:none; background:#000;">
  </iframe>
</div>
```

--------------------------------

### Get Hub Health and Version

Source: https://paps-jp.github.io/paprika/worker-autodeploy.html

Retrieve the current version hash of the hub. This is used to verify the hub's status and compare it with worker versions.

```bash
curl -s http://10.10.50.34:8000/health | python -c "import json,sys; print(json.load(sys.stdin)['version'])"
```

--------------------------------

### Execute JavaScript and Get Title

Source: https://paps-jp.github.io/paprika/api.html

Shows how to execute arbitrary JavaScript code within the page context and retrieve its return value. Useful for interacting with the page's JavaScript environment or fetching data.

```python
title = await page.evaluate("document.title")
data  = await page.evaluate("fetch('/api').then(r=>r.json())", await_promise=True)
```

```python
title = page.evaluate("document.title")
data  = page.evaluate("fetch('/api').then(r=>r.json())", await_promise=True)
```

--------------------------------

### Iterate and Get Attribute with Locator

Source: https://paps-jp.github.io/paprika/api.html

Iterates through all elements matching a selector, prints their 'data-id' attribute, and then clicks the first element. Requires awaiting the 'all()' call.

```python
rows = page.locator(".item")
for r in await rows.all():
    print(await r.get_attribute("data-id"))
await rows.first.click()
```

--------------------------------

### Iterate and Get Attribute with Locator (Synchronous)

Source: https://paps-jp.github.io/paprika/api.html

Iterates through all elements matching a selector, prints their 'data-id' attribute, and then clicks the first element. This version uses synchronous iteration for 'all()'.

```python
rows = page.locator(".item")
for r in rows.all():
    print(r.get_attribute("data-id"))
rows.first.click()
```

--------------------------------

### Display Multiple Paprika Sessions

Source: https://paps-jp.github.io/paprika/vnc-embed.html

This example shows how to display multiple Paprika worker screens simultaneously on a single page using CSS Grid and iframe elements. It's suitable for creating dashboards with several concurrent sessions.

```html
<div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 8px; height: 600px;">
  <iframe src="https://paprika.example.com/sessions/ses_aaaa/novnc/?path=sessions/ses_aaaa/novnc/websockify&autoconnect=1&resize=scale&reconnect=1&view_only=true"></iframe>
  <iframe src="https://paprika.example.com/sessions/ses_aaab/novnc/?path=sessions/ses_aaab/novnc/websockify&autoconnect=1&resize=scale&reconnect=1&view_only=true"></iframe>
  <iframe src="https://paprika.example.com/sessions/ses_aaac/novnc/?path=sessions/ses_aaac/novnc/websockify&autoconnect=1&resize=scale&reconnect=1&view_only=true"></iframe>
  <iframe src="https://paprika.example.com/sessions/ses_aaad/novnc/?path=sessions/ses_aaad/novnc/websockify&autoconnect=1&resize=scale&reconnect=1&view_only=true"></iframe>
</div>
```

--------------------------------

### Paprika SDK のインストール

Source: https://paps-jp.github.io/paprika/intro.html

ソースツリーからローカルインストールするか、GitHub リポジトリから直接インストールします。

```bash
# ソースツリーから
pip install -e ./client/python
```

```bash
# または直接
pip install "git+https://github.com/paps-jp/paprika.git#subdirectory=client/python"
```

--------------------------------

### Launch All-in-One Docker Server

Source: https://paps-jp.github.io/paprika/operations.html

Use this command to set up and run the entire Paprika server (Redis, Hub, Worker, Agent) on a single host using Docker Compose. This is suitable for testing and small to medium-scale deployments.

```bash
git clone https://github.com/paps-jp/paprika.git
cd paprika
cp .env.example .env
docker compose up -d --build
```

--------------------------------

### 最初のスクリプト: ページタイトルとリンクの取得

Source: https://paps-jp.github.io/paprika/intro.html

指定した URL のページタイトルと全てのリンクを取得する基本的なスクリプト例です。`cli.session()` はブラウザタブを確保し、ブロックを抜けると自動で閉じます。

```python
import asyncio
from paprika_client import async_paprika

async def main():
    async with async_paprika.connect() as cli:
        async with cli.session("https://news.ycombinator.com") as page:
            print(await page.title())
            for url in await page.links(urls_only=True):
                print(url)

asyncio.run(main())
```

--------------------------------

### Launch Hub with Redis Persistence via CLI

Source: https://paps-jp.github.io/paprika/operations.html

Run the Paprika Hub using Python CLI, configured to use Redis for persistent storage of job data. This is suitable for development environments requiring data persistence.

```bash
# Redis 永続化付き
python -m server --mode hub --port 8000 \
  --redis-url redis://localhost:6379 \
  --data-dir ./data/jobs
```

--------------------------------

### Login and Fetch Content Using Saved Cookies

Source: https://paps-jp.github.io/paprika/guides.html

Demonstrates how to log in to a website, save the session cookies, and then use those cookies to fetch content from a protected page on subsequent requests.

```python
# 1) セッションでログイン（手動 noVNC でも page 操作でも）
async with cli.session("https://market.example.com/login",
                       parent_job_id="login") as page:
    await page.fill("input[name=email]", "user@example.com")
    await page.fill("input[name=password]", "******")
    await page.click("button[type=submit]")
    await page.save_cookies_to_host(all_cookies=True)   # Cookie を保存

# 2) 以後は cookies_from で会員ページを収集
job = await cli.fetch("https://market.example.com/item/xxx",
                      cookies_from="market.example.com")
await cli.download_job_assets(job["job_id"], "out/item")
```

--------------------------------

### Connect to Paprika Hub (Async)

Source: https://paps-jp.github.io/paprika/api.html

Establishes a connection to the Paprika hub. The connection defaults to PAPRIKA_HUB or http://localhost:8000. This is the recommended way to connect for asynchronous operations.

```APIDOC
## Connect to Paprika Hub (Async)

### Description
Establishes a connection to the Paprika hub. The connection defaults to PAPRIKA_HUB or http://localhost:8000. This is the recommended way to connect for asynchronous operations.

### Method
`async_paprika.connect(base_url=None, *, token=None, timeout=180.0)`

### Parameters
- **base_url** (string) - Optional - The base URL for the Paprika hub.
- **token** (string) - Optional - Authentication token.
- **timeout** (float) - Optional - Connection timeout in seconds. Defaults to 180.0.

### Usage Example
```python
async with async_paprika.connect() as cli:
    # Use the client for operations
    pass
```
```

--------------------------------

### Retrieve novnc_url after Lane Binding

Source: https://paps-jp.github.io/paprika/vnc-embed.html

Poll the job status using curl to get the novnc_url once a lane has been assigned to the job. This URL is a relative path from the hub.

```shell
$ curl -s https://paprika.example.com/jobs/a3b4c5d6e7f8 | jq .novnc_url

"/sessions/ses_abc123def456/novnc/?path=sessions/ses_abc123def456/novnc/websockify&autoconnect=1&resize=scale&reconnect=1"
```

--------------------------------

### Connect to Paprika Hub (PHP)

Source: https://paps-jp.github.io/paprika/api.html

Establish a connection to the Paprika Hub using the PHP SDK. This method is straightforward and requires only the ext-curl extension.

```php
use Paprika\Client\Paprika;

$cli = Paprika::connect();   // PAPRIKA_HUB or http://localhost:8000
// ...
```

--------------------------------

### Take a Snapshot of a URL

Source: https://paps-jp.github.io/paprika/api.html

Opens a URL and captures a PNG screenshot. Waits for 2 seconds by default. The screenshot is returned as bytes.

```python
await snapshot(url, *, wait=2.0, full_page=False, path=None)
```

--------------------------------

### Connect to Paprika Hub (Sync Python)

Source: https://paps-jp.github.io/paprika/api.html

Use this snippet for a synchronous connection to the Paprika Hub. This is suitable for environments where async/await is not preferred.

```python
with sync_paprika.connect() as cli:
    ...
```

--------------------------------

### PHP SDK Client Methods (Phase 1)

Source: https://paps-jp.github.io/paprika/api.html

Lists the available client methods in the PHP SDK for Phase 1, which includes Job API and Session lifecycle management. These methods largely mirror their Python counterparts with snake_case converted to camelCase.

```APIDOC
## PHP SDK Client Methods (Phase 1)

### Description
Lists the available client methods in the PHP SDK for Phase 1, which includes Job API and Session lifecycle management. These methods largely mirror their Python counterparts with snake_case converted to camelCase.

### Methods
- **`$cli->health()`**: Checks connectivity. (Python: `cli.health()`)
- **`$cli->listWorkers() / listSessions()`**: Lists workers or sessions. (Python: `list_workers / list_sessions`)
- **`$cli->createJob(string $url, array $opts)`**: Creates a new job. (Python: `create_job`)
- **`$cli->fetch(string $url, array $opts = [], bool $wait = true, ...$args)`**: Initiates a fetch job and optionally waits for completion. (Python: `fetch`)
- **`$cli->getJob(string $id) / listJobs() / jobResult(string $id)`**: Retrieves job status or result. (Python: `get_job / list_jobs / job_result`)
- **`$cli->waitJob(string $id, float $pollInterval = 2.0, float $timeout = 600.0)`**: Waits for a job to reach a terminal state. (Python: `wait_job`)
- **`$cli->cancelJob(string $id) / deleteJob(string $id)`**: Cancels or deletes a job.
- **`$cli->jobAssets(string $id, string $kind = null, bool $absolute = true, bool $details = false)`**: Lists job assets. (Python: `job_assets`)
- **`$cli->jobImages(string $id)`**: Shortcut to list job images. (Python: `job_images`)
- **`$cli->downloadJobAssets(string $id, string $destDir, string $kind = 'image')`**: Downloads job assets locally. (Python: `download_job_assets`)
- **`$cli->openSession(string $initialUrl = null, ...$kwargs)`**: Opens a new session. Returns a `Session` object. (Python: `open_session`)
- **`$cli->session(string $url, callable $closure, array $kwargs = [])`**: Opens a session and automatically closes it upon closure of the provided callable. (Python: `async with cli.session(...)` equivalent)
```

--------------------------------

### Download Videos from a Page

Source: https://paps-jp.github.io/paprika/guides.html

Fetches a page and specifically downloads video assets. It also shows how to download HLS/DASH streams as a single MP4 file using yt-dlp within a session.

```python
job = await cli.fetch("https://example.com/clips", play_videos=True, wait_seconds=30)
videos = await cli.job_assets(job["job_id"], kind="video")
await cli.download_job_assets(job["job_id"], "out/videos", kind="video")
```

```python
async with cli.session("https://video.example/watch/123",
                       parent_job_id="video-grab") as page:
    await page.download_video()                # 現ページを yt-dlp
    await page.save_assets("out/videos", kind="video")
```

--------------------------------

### Interactive Browser Session with Paprika Client

Source: https://paps-jp.github.io/paprika/index.html

This snippet demonstrates how to use `cli.session()` for interactive browser control. It allows you to perform actions like clicking elements, filling forms, and taking screenshots within a session.

```python
async with cli.session("https://example.com") as page:
    await page.click("text=ログイン")
    await page.fill("#user", "alice")
    await page.screenshot(path="shot.png")
```

--------------------------------

### Simulate User Input Events

Source: https://paps-jp.github.io/paprika/guides.html

Simulates various user input actions like hovering, selecting an option, checking a checkbox, and uploading a file. Note that hover, select_option, and check simulate events via JavaScript, while set_input_files uses a more direct method.

```javascript
await page.hover(".menu")
await page.select_option("select#country", "JP")
await page.check("#agree")
await page.set_input_files("input[type=file]", "photo.jpg")
```

--------------------------------

### Fetch Job (PHP SDK)

Source: https://paps-jp.github.io/paprika/api.html

Initiates a fetch job for a given URL and waits for its completion. This is a convenience method that combines job creation and waiting.

```APIDOC
## Fetch Job (PHP SDK)

### Description
Initiates a fetch job for a given URL and waits for its completion. This is a convenience method that combines job creation and waiting.

### Method
`$cli->fetch(string $url, array $opts = [], bool $wait = true, ...$args)

### Parameters
- **url** (string) - Required - The URL to fetch.
- **opts** (array) - Optional - Options for the fetch job.
- **wait** (bool) - Optional - Whether to wait for the job to complete. Defaults to true.
- **...$args** - Additional arguments for job creation.

### Request Example
```php
$job = $cli->fetch('https://en.wikipedia.org/wiki/Cat', scroll: true);
```

### Response
- **job** (array) - An array containing job details, including 'status'.
```

--------------------------------

### PaprikaClient Core Methods

Source: https://paps-jp.github.io/paprika/api.html

Provides methods for basic client operations such as checking health, listing connected workers and sessions, and opening new sessions.

```APIDOC
## PaprikaClient (`cli.*`)

### Methods

- **`cli.health()`** → `dict`
  - Description: Checks the connectivity of the client.

- **`cli.list_workers()`** → `list`
  - Description: Lists all currently connected workers.

- **`cli.list_sessions()`** → `list`
  - Description: Lists all active sessions.

- **`cli.session(**kw)`** → `Session`
  - Description: Opens a new session. Can be used with `async with` or `await`. Accepts optional keyword arguments like `parent_job_id`, `worker_id`, `lane_hint`, `idle_ttl_s`, `absolute_ttl_s`, `use_profile`.

- **`cli.open_session(...)`** → `Session`
  - Description: Manually acquires a session. The session must be released using `await page.close()`.
```

--------------------------------

### Construct Full VNC URL

Source: https://paps-jp.github.io/paprika/vnc-embed.html

Prepend the hub's absolute URL to the relative novnc_url obtained from the job details to create a full, embeddable URL.

```javascript
const HUB = 'https://paprika.example.com';
const fullUrl = HUB + novnc_url;
// -> https://paprika.example.com/sessions/ses_abc123def456/novnc/?path=jobs/...&autoconnect=1...
```

--------------------------------

### Crawl a Website with walk()

Source: https://paps-jp.github.io/paprika/guides.html

Automates website crawling by traversing links, handling duplicate URLs, and respecting domain and path restrictions. This is more robust than manual link collection and looping.

```python
from paprika_client import async_paprika, walk

async def main():
    async with async_paprika.connect() as cli:
        async with cli.session("https://example.com",
                               parent_job_id="crawl") as page:
            async for visit in walk(page, target_pages=50, same_domain=True,
                                    deny_paths=["/login", "/cart"]):
                print(visit.n, visit.depth, visit.url)
                await page.save_assets(f"out/{visit.n:04d}")   # 各ページで保存
```

--------------------------------

### PHP SDK Connection

Source: https://paps-jp.github.io/paprika/api.html

Connects to the Paprika hub using the PHP SDK. Requires Composer and PHP 8.1+. This method is synchronous and has no external dependencies beyond ext-curl.

```APIDOC
## Connect to Paprika Hub (PHP SDK)

### Description
Connects to the Paprika hub using the PHP SDK. Requires Composer and PHP 8.1+. This method is synchronous and has no external dependencies beyond ext-curl.

### Method
`Paprika::connect(base_url=None, *, token=None)`

### Parameters
- **base_url** (string) - Optional - The base URL for the Paprika hub. Defaults to PAPRIKA_HUB or http://localhost:8000.
- **token** (string) - Optional - Authentication token.

### Usage Example
```php
use Paprika\Client\Paprika;

$cli = Paprika::connect(); // Uses PAPRIKA_HUB or http://localhost:8000
// Use the client for operations
```
```

--------------------------------

### Page - Cloudflare and Window Resize

Source: https://paps-jp.github.io/paprika/api.html

Utilities for solving Cloudflare challenges and resizing the browser window.

```APIDOC
## Page - Cloudflare and Window Resize

### `page.solve_cloudflare(*, timeout_s=25.0)`

**Description**: Waits for or solves Cloudflare challenges.

### `page.resize_window(width, height)`

**Description**: Resizes the browser window to the specified dimensions.
```

--------------------------------

### Use Synchronous Paprika Client

Source: https://paps-jp.github.io/paprika/guides.html

Provides a synchronous API for web automation, suitable for use in notebooks or existing synchronous Python code. The API mirrors the asynchronous version but without 'await'.

```python
from paprika_client import sync_paprika

with sync_paprika.connect() as cli:
    job = cli.fetch("https://example.com/article")
    for url in cli.job_images(job["job_id"]):
        print(url)

    with cli.session("https://example.com") as page:
        page.click("text=ログイン")
        print(page.title())
```

--------------------------------

### Connect to Paprika Hub (Sync)

Source: https://paps-jp.github.io/paprika/api.html

Establishes a synchronous connection to the Paprika hub. This is a blocking facade for the asynchronous API, suitable for simple scripts or existing synchronous codebases.

```APIDOC
## Connect to Paprika Hub (Sync)

### Description
Establishes a synchronous connection to the Paprika hub. This is a blocking facade for the asynchronous API, suitable for simple scripts or existing synchronous codebases.

### Method
`sync_paprika.connect(base_url=None, *, token=None, timeout=180.0, auto_start=True)`

### Parameters
- **base_url** (string) - Optional - The base URL for the Paprika hub.
- **token** (string) - Optional - Authentication token.
- **timeout** (float) - Optional - Connection timeout in seconds. Defaults to 180.0.
- **auto_start** (bool) - Optional - Automatically start the background asyncio loop. Defaults to True.

### Usage Example
```python
with sync_paprika.connect() as cli:
    # Use the client for operations
    pass
```
```

--------------------------------

### Paprika ハブへの非同期接続とヘルスチェック

Source: https://paps-jp.github.io/paprika/intro.html

非同期クライアントを使用して Paprika ハブに接続し、ヘルスチェックを行います。環境変数 PAPRIKA_HUB が自動的に参照されます。

```python
import asyncio
from paprika_client import async_paprika

async def main():
    async with async_paprika.connect() as cli:   # PAPRIKA_HUB を自動参照
        print(await cli.health())

asyncio.run(main())
```

--------------------------------

### Making HTTP Requests with CLI

Source: https://paps-jp.github.io/paprika/operations.html

Use the internal CLI method `_json` to make raw HTTP requests to the Paprika API for endpoints not yet wrapped by the SDK, such as registry-related operations.

```python
await cli._json("GET", "/hosts")
```

--------------------------------

### Display Image Details from a Job

Source: https://paps-jp.github.io/paprika/guides.html

Fetches image assets with details from a job, then iterates through them to print information such as size, MIME type, name, and URLs.

```python
import asyncio
from paprika_client import async_paprika

async def main():
    async with async_paprika.connect() as cli:
        # 1) ページを取得して画像を集める
        job = await cli.fetch("https://en.wikipedia.org/wiki/Cat", scroll=True)

        # 2) 画像一覧（メタ付き dict のリスト）を取得
        rows = await cli.job_assets(job["job_id"], kind="image", details=True)

        # 3) for で 1 件ずつ詳細を出力
        print(f"{len(rows)} 枚の画像:")
        for i, a in enumerate(rows, 1):
            print(f"[{i:3}] {a['size_h']:>10}  {a['mime'] or '-':<12}  {a['name']}")
            print(f"      URL:  {a['url']}")
            if a.get("source_url"):
                print(f"      元:   {a['source_url']}")

asyncio.run(main())
```

--------------------------------

### Open Session (PHP SDK)

Source: https://paps-jp.github.io/paprika/api.html

Opens a new browser session. This method can be used to manage the lifecycle of a session, either directly or via a closure.

```APIDOC
## Open Session (PHP SDK)

### Description
Opens a new browser session. This method can be used to manage the lifecycle of a session, either directly or via a closure.

### Method
`$cli->openSession(string $initialUrl = null, ...$kwargs)

### Parameters
- **initialUrl** (string) - Optional - The initial URL to navigate to.
- **...$kwargs** - Additional keyword arguments for session configuration.

### Returns
- **Session** - A Session object representing the browser session.

### Usage Example (with closure)
```php
use Paprika\Client\Session;

$cli->session('https://example.com', function (Session $sess) use ($cli) {
    echo "noVNC: " . $cli->baseUrl() . $sess->novncUrl, "\n";
    // Phase 2 methods like $sess->goto(), $sess->locator() will be available here.
});
```
```

--------------------------------

### Page Navigation and Input

Source: https://paps-jp.github.io/paprika/api.html

Demonstrates navigating to a URL, filling an input field, pressing Enter, and uploading files using the page object. This is typically used for automated browser interactions.

```python
await page.goto("https://example.com")
await page.fill("#email", "user@example.com")
await page.press("Enter")
await page.set_input_files("input[type=file]", ["a.jpg", "b.jpg"])
```

```python
page.goto("https://example.com")
page.fill("#email", "user@example.com")
page.press("Enter")
page.set_input_files("input[type=file]", ["a.jpg", "b.jpg"])
```

--------------------------------

### Download All Images from an Article Page

Source: https://paps-jp.github.io/paprika/index.html

Use this snippet to download all images from a given article URL. It connects to the Paprika client, fetches the page content, and then downloads all associated assets to a specified directory.

```python
import asyncio
from paprika_client import async_paprika

async def main():
    async with async_paprika.connect() as cli:
        job = await cli.fetch("https://example.com/article")   # 開いて収集
        await cli.download_job_assets(job["job_id"], "out/")   # 画像を保存

asyncio.run(main())
```

--------------------------------

### Page Navigation and Interaction

Source: https://paps-jp.github.io/paprika/api.html

Provides methods for navigating web pages, interacting with elements, and managing browser state.

```APIDOC
## Page — Navigation and Operations

### Properties (Read-only)

- `page.url`: Current page URL.
- `page.session_id`: ID of the current session.
- `page.worker_id`: ID of the worker handling the page.
- `page.lane_idx`: Index of the lane.
- `page.novnc_url`: URL for NoVNC access.
- `page.page_id`: ID of the page.

### Methods

- **`page.goto(url)`** → `dict`
  - Description: Navigates the page to a specified URL.

- **`page.back()`**, **`page.forward()`**, **`page.history_first()`**, **`page.reload()`**
  - Description: Navigates through browser history or reloads the current page.

- **`page.click(selector)`** → `dict`
  - Description: Clicks on an element identified by a CSS selector. Supports `[@N]` for `[data-paprika-id="N"]` expansion.

- **`page.fill(selector, value)`** → `dict`
  - Description: Sets the value of an input or textarea element and triggers input/change events.

- **`page.press(key, *, count=1, modifiers=None)`** → `dict`
  - Description: Simulates pressing a key. Supports key names (e.g., `"Enter"`) and `modifiers` (e.g., `["Ctrl"]`).

- **`page.type(text)`** → `dict`
  - Description: Inserts text into the currently focused element.

- **`page.scroll(direction="down", pixels=800)`** → `dict`
  - Description: Scrolls the page in a specified direction by a given number of pixels.

- **`page.hover / dblclick / focus / scroll_into_view_if_needed (selector, *, index=0)`** → `bool`
  - Description: Simulates input device actions like hover, double-click, focus, or scrolling an element into view.

- **`page.select_option(selector, value, *, index=0)`** → `bool`
  - Description: Selects an option in a `<select>` element.

- **`page.check / uncheck (selector, *, index=0)`** → `bool`
  - Description: Checks or unchecks a checkbox or radio button.

- **`page.set_input_files(selector, files)`** → `dict`
  - Description: Uploads files to an input element. `files` can be a path or a list of paths. Uses CDP.
```

--------------------------------

### Fetch Images from a URL

Source: https://paps-jp.github.io/paprika/guides.html

Fetches all images from a given URL, including handling lazy loading by scrolling. It then downloads the collected images to a specified directory.

```python
import asyncio
from paprika_client import async_paprika

async def main():
    async with async_paprika.connect() as cli:
        job = await cli.fetch("https://example.com/article", scroll=True)
        images = await cli.job_images(job["job_id"])        # 画像URL一覧
        print(len(images), "枚")
        await cli.download_job_assets(job["job_id"], "out/images")  # 保存

asyncio.run(main())
```

--------------------------------

### Interact with a Web Page Using a Session

Source: https://paps-jp.github.io/paprika/guides.html

Opens a web page within a session, performs actions like clicking and scrolling, retrieves image URLs, and saves assets. Requires a parent job ID for asset saving.

```python
async with cli.session("https://news.ycombinator.com") as page:
    await page.locator(".athing .titleline > a").click()
    await page.scroll()                       # 遅延ロードを発火
    srcs = await page.assets()                # このページの画像URL
    await page.save_assets("out/images")
```

--------------------------------

### Check Worker Versions for Drift

Source: https://paps-jp.github.io/paprika/worker-autodeploy.html

Fetch the versions of all connected workers and display a summary of version distribution. This helps identify workers that have not yet updated.

```bash
curl -s http://10.10.50.34:8000/workers | python -c "
import json,sys
d = json.load(sys.stdin)
versions = {}
for w in d['workers']:
    versions.setdefault(w.get('version','?'), []).append(w['address'])
for v, ips in sorted(versions.items()):
    print(f'{v}: {len(ips)} workers · {", ".join(ips[:3])}{"..." if len(ips)>3 else ""}')
"
```

--------------------------------

### Restart Hub for Deployment

Source: https://paps-jp.github.io/paprika/worker-autodeploy.html

Restart the hub service on the host machine after pulling the latest changes from the main branch.

```bash
ssh 10.10.50.34 'cd /opt/paprika && git pull --ff-only origin main && docker compose restart hub'
```

--------------------------------

### Site Crawling (walk / Walker)

Source: https://paps-jp.github.io/paprika/api.html

High-level helper for crawling websites, including queue management, deduplication, and filtering.

```APIDOC
## Site Crawling (walk / Walker)

### `walk(page, **opts)`

**Description**: An asynchronous iterator that yields `Visit` objects for crawling a website. It handles queueing, deduplication, domain/path filtering, and off-scope redirect following.

### `Walker` Class

**Description**: The class-based version of the `walk` function.

### `Visit` Object

**Properties**: `n`, `url`, `requested_url`, `depth`, `outline`, `page` (the `Page` object for the current visit).

### Options (`**opts`)
- `start_url` (string): The starting URL for the crawl. Defaults to the current page's URL.
- `target_pages` (int): The maximum number of pages to visit. Defaults to 100.
- `same_domain` (bool): Whether to restrict crawling to the same domain. Defaults to True.
- `allowed_domains` (list[str]): A list of allowed domains.
- `allow_paths` (list[str]): Paths that are allowed.
- `deny_paths` (list[str]): Paths that are denied.
- `deny_defaults` (bool): Whether to use default denied paths. Defaults to True.
- `order` (str): The exploration order ('bfs' or 'dfs'). Defaults to 'bfs'.
- `max_depth` (int): The maximum link depth to explore.
- `per_page_timeout_s` (float): Timeout in seconds for processing each page. Defaults to 30.0.
- `persist_state` (bool): Whether to persist crawl progress to the parent job for resuming. Defaults to True.
- `host_dedup` (bool): Whether to deduplicate visited URLs across different hosts. Defaults to False.

**Note**: `walk` is currently only available in the async API. For use in synchronous scripts, wrap the async example with `asyncio.run()` or adapt the walk part to run asynchronously and collect results.
```

--------------------------------

### Retrieve Assets from an Existing Job

Source: https://paps-jp.github.io/paprika/guides.html

Lists existing jobs and retrieves images and asset details from the most recent job. It also downloads all assets associated with that job.

```python
jobs   = await cli.list_jobs()                 # 一覧（新しい順）
job_id = jobs[0]["job_id"]
images = await cli.job_images(job_id)          # 画像URL一覧
rows   = await cli.job_assets(job_id, details=True)  # メタ付き(size/source_url/mime)
await cli.download_job_assets(job_id, f"out/{job_id}")
```

--------------------------------

### Session Object Methods (PHP SDK)

Source: https://paps-jp.github.io/paprika/api.html

Details the methods available on the Session object in the PHP SDK (Phase 1), including closing and detaching the session.

```APIDOC
## Session Object Methods (PHP SDK)

### Description
Details the methods available on the Session object in the PHP SDK (Phase 1), including closing and detaching the session.

### Methods
- **`$sess->close()`**: Closes the session. This operation is idempotent and safe. Corresponds to `DELETE /sessions/{id}`.
- **`$sess->detach()`**: Detaches the session, skipping the automatic closure behavior associated with closures. Corresponds to `POST /sessions/{id}/detach`.
- **Phase 2 Methods**: Methods like `goto`, `click`, `fill`, `locator`, `screenshot`, `state`, `outline`, etc., will be available in Phase 2.
```

--------------------------------

### Exception Handling (PHP SDK)

Source: https://paps-jp.github.io/paprika/api.html

Describes the exception classes used by the Paprika PHP SDK for error handling.

```APIDOC
## Exception Handling (PHP SDK)

### Description
Describes the exception classes used by the Paprika PHP SDK for error handling.

### Exception Classes
- **`Paprika\Client\PaprikaError`**: Handles HTTP or transport-related errors. The `statusCode` property can be used to retrieve the HTTP status code (or null if it's a transport error).
- **`Paprika\Client\PaprikaActionError`**: Handles errors related to Page/Locator operations. This class will be more extensively used in Phase 2.
```

--------------------------------

### Emergency Restart of All Workers

Source: https://paps-jp.github.io/paprika/worker-autodeploy.html

Initiate a restart for a range of worker instances. This is a broad action to resolve issues like widespread WS half-open connections.

```bash
ssh 10.10.50.34 'for IP in 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164; do
  ssh -o ConnectTimeout=3 -o BatchMode=yes root@10.10.50.$IP \
    "docker compose -f /opt/paprika/docker-compose-worker.yml restart worker" & 
done; wait'
```

--------------------------------

### One-Shot Helpers

Source: https://paps-jp.github.io/paprika/api.html

Utility functions for performing single actions and closing the session.

```APIDOC
## One-Shot Helpers

Import these functions from `paprika_client`: `snapshot`, `outline`, `state`, `run`.

### `snapshot(url, *, wait=2.0, full_page=False, path=None)`

**Description**: Opens a URL, waits for a specified time, and returns the page as a PNG image (bytes). Optionally captures the full page and saves to a path.

### `outline(url, *, wait=2.0)`

**Description**: Opens a URL, waits, and returns the page's outline as a string.

### `state(url, *, wait=2.0)`

**Description**: Opens a URL, waits, and returns the page's state (URL, title, etc.) as a dictionary.

### `run(actions, *, initial_url=None)`

**Description**: Executes a sequence of actions (from `act.*`) and returns the result. Can start from an initial URL.
```

--------------------------------

### Use Locators for Delayed Resolution and Chaining

Source: https://paps-jp.github.io/paprika/guides.html

Utilizes locators for delayed element resolution and chaining actions. This allows for more robust element interaction, especially in dynamic web pages.

```javascript
rows = page.locator(".item")
for r in await rows.all():
    print(await r.get_attribute("data-id"))
await page.get_by_text("ログイン").click()
```
Tokens:
Raw