grove.network.request()

Make a bounded native HTTPS request outside browser CORS.

Signature

grove.network.request(url: string, options?: {
  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
  headers?: Record<string, string | number>
  body?: string | Uint8Array | ArrayBuffer | null
}): Promise<GroveNetworkResponse>

Availability

Runtime with network.request and an accepted HTTPS hostPermissions destination. Settings pages cannot request network access.

Parameters

Parameter	Required	Description
`url`	Yes	HTTPS URL, at most 8,192 UTF-8 bytes; must pass host-permission and destination checks.
`options.method`	No	Default GET; supplied method is uppercased. HEAD and OPTIONS are not supported.
`options.headers`	No	Plain object, default {}; at most 12 entries. Do not pass a browser Headers object.
`options.body`	No	UTF-8 string or bytes, at most 512 KiB (524,288 bytes). Omitted/null means no body. Objects, FormData, Blob, URLSearchParams, and streams are not accepted directly.

Return value

Resolves to the frozen response shape below for every received HTTP status, including redirects and 4xx/5xx responses. HTTP failures set ok to false; transport/permission/validation failures reject.

Behavior and errors

Allowed request headers (case-insensitive): Accept, Authorization, Content-Type, If-Match, If-None-Match, X-API-Key, X-Immich-Session-Token, X-Immich-User-Token. Values must be strings or finite numbers, at most 16,384 UTF-8 bytes, without control characters. Names are at most 64 bytes. Host, Cookie, Origin, proxy, forwarding, and arbitrary custom headers are rejected.

Four requests may run concurrently per extension host, with a 30-second timeout and 8 MiB response body limit. Connections use validated pinned DNS addresses and private-address policy. No browser/shared cookies are sent; Set-Cookie is ignored. Redirects are never automatically followed. Validate any Location before issuing another request, which undergoes all checks again. No signal, credentials, redirect, or timeout option is supported.

The response is not a browser Response: it has no statusText, url, clone, arrayBuffer, stream, or Headers instance.

interface GroveNetworkResponse {
  readonly status: number
  readonly ok: boolean // status 200 through 299
  readonly headers: Readonly<Record<string, string>>
  readonly body: Uint8Array
  text(): string
  json(): unknown
}

headers is a lower-case name/value object containing only cache-control, content-length, content-type, etag, last-modified, and location when present and at most 4,096 UTF-8 bytes per value. The body is buffered; the wrapper is frozen but the byte array remains mutable. Do not mutate it before decoding.

Example

try {
  const response = await grove.network.request('https://api.example.com/items', {
    method: 'POST',
    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
    body: JSON.stringify({ limit: 10 })
  })
  if (!response.ok) throw new Error('HTTP request was unsuccessful')
  const payload = response.json()
  // Validate payload before rendering or using its fields.
} catch {
  console.error('Could not load items.')
}

See response.text(), response.json(), and Security model.