# 外部 API の取得 (CORS 回避)

壁紙は `fluxlay://` という独立した origin で動作するため、外向きの HTTP リクエストは 2 段階のゲートを通ります:

1. **CSP `connect-src`** — `fluxlay.yaml` の `network:` で宣言した origin にしか到達できない。
2. **CORS** — CSP を通過しても、相手サーバが `Access-Control-Allow-Origin` を返さなければブラウザがレスポンスをブロックする。

普通の REST API は CORS を返してくれるのでそのまま `fetch` で動きますが、ICS フィードや公開 RSS、静的ファイルホストなど CORS を意識していないエンドポイントだと 2 番目の壁で止まります。その場合は `proxiedFetch` を使ってください。

## 通常パターン: 直接 `fetch`

CORS を返す API なら何もせず標準の `fetch` で OK です。`network:` だけ宣言します。

```yaml
# fluxlay.yaml
network:
  - origin: https://api.github.com
    reason: Open PR と review-requested PR の取得。
```

```tsx
const res = await fetch("https://api.github.com/search/issues?q=is:open+is:pr+author:@me", {
  headers: { Authorization: `Bearer ${token}` }
});
```

## CORS で弾かれた時: `proxiedFetch`

ブラウザに「Origin ... is not allowed by Access-Control-Allow-Origin」と怒られたら、相手サーバが CORS を返していないサインです。`fetch` を `proxiedFetch` に置き換えるだけで動きます。

```yaml
# fluxlay.yaml
network:
  - origin: https://calendar.google.com
    reason: 公開 ICS カレンダーの取得。
```

```tsx
import { proxiedFetch } from "@fluxlay/react";

const res = await proxiedFetch("https://calendar.google.com/calendar/ical/.../basic.ics");
const ics = await res.text();
```

`proxiedFetch` の中身は `POST /v1/network-proxy` 経由でホスト (Rust) にリクエストを投げるだけです。ホスト側で実際の fetch が行われるためブラウザの CORS は適用されません。target URL の origin が `network:` に宣言されているかはホストが検証するので、セキュリティモデルは直接 `fetch` と同じです。

## どちらを使うか

迷ったら **直接 `fetch` を試して、CORS エラーが出たら `proxiedFetch`** に切り替えてください。`proxiedFetch` はストリーミング非対応・10 MiB 上限などの制約があるので、対応しているなら直接 `fetch` の方が素直です。

| 状況                                     | 推奨                   |
| ---------------------------------------- | ---------------------- |
| 相手サーバが CORS を返す (大半の API)    | `fetch`                |
| ICS / RSS / 静的ファイル等で CORS が無い | `proxiedFetch`         |
| バイナリストリーム / Server-Sent Events  | `fetch` (proxy 非対応) |

## よくあるハマりどころ

- **`network:` 宣言を忘れている** → CSP `connect-src` で弾かれて `Failed to fetch` になる。エラーメッセージにヒントが無いので、まず yaml を確認する。
- **GitHub に `User-Agent` 必須エラー** → `proxiedFetch` 経由なら `Fluxlay-Wallpaper-Proxy/<version>` が自動付与されるので追加対応不要。
- **Cookie が送られない** → `proxiedFetch` は `Cookie` ヘッダを意図的に転送しない。認証は `Authorization` ヘッダで明示的に渡す。

詳細は [proxiedFetch リファレンス](/ja/studio/developer/reference/sdk/proxied-fetch.md)を参照してください。