Fetch External APIs (CORS workaround)

Wallpapers run in an isolated fluxlay:// origin, so outbound HTTP requests pass two gates:

1. CSP connect-src — only origins declared under network: in fluxlay.yaml are reachable.
2. CORS — even after CSP allows the origin, the browser blocks the response unless the upstream returns Access-Control-Allow-Origin.

Most REST APIs return CORS headers, so plain fetch works fine. But a lot of useful endpoints don't — ICS calendar feeds, public RSS, static file hosts. For those, use proxiedFetch.

Normal case: direct fetch

If the API returns CORS headers, declare its origin and use fetch as usual.

# fluxlay.yaml
network:
  - origin: https://api.github.com
    reason: Fetch open and review-requested PRs.

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

When you hit a CORS error: proxiedFetch

If the browser logs Origin ... is not allowed by Access-Control-Allow-Origin, the upstream isn't returning CORS headers. Replace fetch with proxiedFetch — the rest stays the same.

# fluxlay.yaml
network:
  - origin: https://calendar.google.com
    reason: Fetch the user's public ICS calendar feed.

import { proxiedFetch } from "@fluxlay/react";
 
const res = await proxiedFetch("https://calendar.google.com/calendar/ical/.../basic.ics");
const ics = await res.text();

Internally proxiedFetch sends the request description to POST /v1/network-proxy, and the Rust host performs the actual fetch. CORS is a browser-side rule, so it doesn't apply to the host. The host still validates that the target URL's origin is declared in network:, so the security model is identical to direct fetch.

Which one should I use?

Try fetch first. If you get a CORS error, switch to proxiedFetch. proxiedFetch has a few limitations (no streaming, 10 MiB body cap), so prefer the direct path when it works.

Common pitfalls

• Forgot to declare network: — CSP connect-src blocks the request and you get Failed to fetch with no clear hint. Always check the manifest first.
• GitHub returns 403 "User-Agent required" — proxiedFetch sets Fluxlay-Wallpaper-Proxy/<version> automatically. No action needed.
• Cookies aren't sent — proxiedFetch deliberately strips the Cookie header. Pass auth via Authorization instead.

See the proxiedFetch reference for full details.