feat: add shared fetchJson helper for API calls

README.md

@@ -146,6 +146,34 @@ signalReady()
 - `scrubSensitiveData(event)` - Sentry `beforeSend` hook that redacts values of settings keys matching `token`, `secret`, `password`, or `credential` with `[REDACTED]`. Drops the event if it cannot be safely serialized.
 - `reportError(error, context?)` - Capture an exception via Sentry with optional extra context.
 
+### HTTP Requests
+
+- `fetchJson<T>(url, options?)` - Fetch a URL and parse the response body as JSON. Throws a `FetchJsonError` (with `status`, `statusText`, `url`, and an optional `body` holding the parsed error payload when the server returned one) if the response is not ok. Throws a `FetchJsonParseError` (with `url` and the raw `body` string) if the response is ok but its body is not valid JSON. An ok response with an empty body resolves to `undefined`.
+- `fetchJsonOrDefault<T>(url, fallback, options?, warningMessage?)` - Same as `fetchJson`, but catches any error, logs it with `console.warn` (using `warningMessage` if provided), and returns `fallback` instead of throwing.
+
+Both requests are aborted after a default timeout of 8 seconds (`DEFAULT_TIMEOUT_MS`) unless overridden via `options.timeoutMs`. Pass `0` or `Infinity` to disable the timeout entirely.
+
+```typescript
+const settings = await fetchJson<Settings>('https://api.example.com/settings')
+
+const settingsWithFallback = await fetchJsonOrDefault<Settings>(
+  'https://api.example.com/settings',
+  defaultSettings,
+)
+```
+
+```typescript
+const settingsWithTimeout = await fetchJson<Settings>(
+  'https://api.example.com/settings',
+  { timeoutMs: 3000 },
+)
+
+const settingsNoTimeout = await fetchJson<Settings>(
+  'https://api.example.com/settings',
+  { timeoutMs: 0 },
+)
+```
+
 ## Web Components
 
 This library includes reusable web components for building consistent Edge Apps. See the [components documentation](https://github.com/Screenly/edge-apps-library/blob/main/docs/components.md) for usage details.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@screenly/edge-apps",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A TypeScript library for interfacing with Screenly Edge Apps API",
   "type": "module",
   "sideEffects": [