# 站點請求

<Badge type="warning" text="尚未發布" />

讓背景任務用 Cowork 在某個網站上的分頁的登入狀態，呼叫該網站的 API。那裡沒有開啟分頁時，Cowork 會在背景開啟一個。Cowork 從那個分頁發出請求；cookie、token 或標頭都不會到達 Extension。只允許 `dozin.sites` 列出的站點、方法和路徑。

## dozin.sites

| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `host` | `string` | 是 | 小寫主機名稱，不含協定、連接埠或路徑 |
| `methods` | `string[]` | 是 | `GET`、`POST`、`PUT`、`PATCH`、`DELETE` 中的任意幾個 |
| `pathPrefixes` | `string[]` | 是 | 1–16 個路徑，請求必須以其中之一開頭 |
| `minIntervalMs` | `number` | 否 | 對這個主機的兩次請求之間的最短間隔；預設 1000，最多 60000 |

## ctx.site.request(request) <Badge type="warning" text="尚未發布" />

| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `request.host` | `string` | 是 | `dozin.sites` 裡的一個 `host` |
| `request.method` | `string` | 否 | 預設 `GET` |
| `request.path` | `string` | 是 | 以 `/` 開頭，且以某個 `pathPrefixes` 開頭；不含 `?`、`#`、`..` |
| `request.query` | `Record<string, string \| number \| boolean>` | 否 | 每個鍵一個值 |
| `request.body` | `unknown` | 否 | JSON 主體；`GET` 不可使用 |

### 回傳值

`Promise<{ status: number, contentType: string | null, body: unknown }>`。回應為 JSON 時，`body` 是解析後的 JSON。

### 錯誤

promise 會以一個錯誤拒絕，其 `code` 為：

| `code` | 意思 |
|---|---|
| `NEED_LOGIN` | Cowork 無法在該網站開啟分頁，或網站回應使用者未登入 |
| `SITE_NOT_ALLOWED` | 主機、方法或路徑不在 `dozin.sites` 裡 |
| `RATE_LIMITED` | 網站回應 429 |
| `NETWORK_ERROR` | 請求沒有到達網站 |
| `BAD_REQUEST` | query 或 body 無效、`GET` 帶了 body，或參數無法傳給 Cowork |
| `RUN_ENDED` | 發出這次呼叫的那次執行已經結束 |

## ctx.site.session(host) <Badge type="warning" text="尚未發布" />

判斷使用者在該網站上是否看起來已登入。

| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `host` | `string` | 是 | `dozin.sites` 裡的一個 `host` |

回傳 `Promise<{ loggedIn: boolean | null }>`：有對該網站的上一次請求時，為那次請求的結果；否則該網站有開啟的分頁時為 `null`（Cowork 還無法判斷），沒有時為 `false`。

## 示例

```js
const { loggedIn } = await ctx.site.session('welladjustedhk.janeapp.com');
if (loggedIn === false) return ctx.status('Please log in to Jane', 'warn');
try {
  const res = await ctx.site.request({ host: 'welladjustedhk.janeapp.com', path: '/admin/api/v2/locations' });
  ctx.status(`OK · HTTP ${res.status}`);
} catch (error) {
  ctx.status(error.code === 'NEED_LOGIN' ? 'Please log in to Jane' : `Error: ${error.code}`, 'error');
}
```

## 相關

- [背景任務](https://docs.micromeet.ai/zh-tw/extension-sdk/service.md): `ctx.site` 從哪裡來
- [概覽](https://docs.micromeet.ai/zh-tw/extension-sdk/overview.md): `package.json` 欄位