@screenly/edge-apps 1.3.0 → 1.4.0

package/README.md

@@ -140,12 +140,67 @@ signalReady()
 - `addUTMParams(url, params?)` - Add UTM parameters to URL
 - `addUTMParamsIf(url, enabled, params?)` - Conditionally add UTM parameters
 
+### Edge App Cache
+
+- `readEdgeAppCache(namespace, key)` - Read a `localStorage`-backed, namespaced last-known-good value
+- `writeEdgeAppCache(namespace, key, value)` - Write a `localStorage`-backed, namespaced last-known-good value
+
 ### Error Reporting (Sentry)
 
 - `setupSentry(app, contexts?)` - Initialize Sentry using the `sentry_dsn` setting; sets the `edge_app` tag, hostname, and any additional contexts. No-ops if `sentry_dsn` is not configured.
 - `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.
 
+## Edge App Cache
+
+When an Edge App fetches data from a backend, a failure shouldn't necessarily
+break the display — falling back to the last-known-good value is often better
+than showing an error.
+
+### `readEdgeAppCache(namespace, key)` / `writeEdgeAppCache(namespace, key, value)`
+
+Read/write a `localStorage`-backed value under `namespace`, so different
+apps/caches don't collide. There is no TTL: it's meant to store the
+last-known-good value and be consulted only after a genuine fetch failure, not
+as a general-purpose expiring cache — and `localStorage` itself isn't
+guaranteed to survive a device reboot. Both fail silently (return `null` /
+no-op) if storage is unavailable, disabled, or full — so it's safe to use
+without extra error handling around it.
+
+`writeEdgeAppCache()` accepts any JSON-serializable value (object, array,
+string, number, etc.) — `WeatherData` below is just a stand-in name for
+"whatever your fetch returns," not a type this library exports.
+
+```typescript
+import {
+  readEdgeAppCache,
+  writeEdgeAppCache,
+  getSettingWithDefault,
+} from '@screenly/edge-apps'
+
+async function loadWeather() {
+  const displayErrors = getSettingWithDefault('display_errors', false)
+
+  try {
+    const response = await fetch(weatherApiUrl)
+    if (!response.ok) throw new Error(`Weather API returned ${response.status}`)
+
+    // weatherData can be any JSON-serializable shape, e.g.:
+    // { temperature: 18, description: 'Cloudy', unit: 'metric' }
+    const weatherData: WeatherData = await response.json()
+    writeEdgeAppCache('my-edge-app', 'weather', weatherData)
+    return weatherData
+  } catch (error) {
+    // When `display_errors` is on, the raw error always wins, by design, so
+    // operators can diagnose real problems instead of seeing stale data.
+    if (!displayErrors) {
+      return readEdgeAppCache<WeatherData>('my-edge-app', 'weather')
+    }
+    throw error
+  }
+}
+```
+
 ## 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/dist/utils/edge-app-cache.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads and JSON-parses the value stored under `${namespace}:${key}` in
+ * `localStorage`, or `null` if missing, unreadable, or storage is
+ * unavailable. Meant for last-known-good fallback data for Edge Apps:
+ * consult it only after a genuine fetch failure, not as a general-purpose
+ * expiring cache — there is no TTL, and `localStorage` itself isn't
+ * guaranteed to survive a device reboot.
+ */
+export declare function readEdgeAppCache<T>(namespace: string, key: string): T | null;
+/**
+ * JSON-serializes and stores `value` under `${namespace}:${key}` in
+ * `localStorage`. Fails silently if storage is unavailable, disabled, or
+ * full.
+ */
+export declare function writeEdgeAppCache(namespace: string, key: string, value: unknown): void;
+//# sourceMappingURL=edge-app-cache.d.ts.map

package/dist/utils/edge-app-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-app-cache.d.ts","sourceRoot":"","sources":["../../src/utils/edge-app-cache.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAU5E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACb,IAAI,CAWN"}

package/dist/utils/edge-app-cache.js

@@ -0,0 +1,49 @@
+function getStorage() {
+    try {
+        if (typeof localStorage === 'undefined')
+            return null;
+        return localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads and JSON-parses the value stored under `${namespace}:${key}` in
+ * `localStorage`, or `null` if missing, unreadable, or storage is
+ * unavailable. Meant for last-known-good fallback data for Edge Apps:
+ * consult it only after a genuine fetch failure, not as a general-purpose
+ * expiring cache — there is no TTL, and `localStorage` itself isn't
+ * guaranteed to survive a device reboot.
+ */
+export function readEdgeAppCache(namespace, key) {
+    const storage = getStorage();
+    if (!storage)
+        return null;
+    try {
+        const raw = storage.getItem(`${namespace}:${key}`);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * JSON-serializes and stores `value` under `${namespace}:${key}` in
+ * `localStorage`. Fails silently if storage is unavailable, disabled, or
+ * full.
+ */
+export function writeEdgeAppCache(namespace, key, value) {
+    const storage = getStorage();
+    if (!storage)
+        return;
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined)
+            return;
+        storage.setItem(`${namespace}:${key}`, serialized);
+    }
+    catch {
+        // Storage disabled or quota exceeded; caller simply has nothing cached.
+    }
+}

package/dist/utils/index.d.ts

@@ -1,5 +1,6 @@
 export * from './calendar.js';
 export * from './error-handling.js';
+export * from './edge-app-cache.js';
 export * from './html.js';
 export * from './theme.js';
 export * from './locale.js';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA"}

package/dist/utils/index.js

@@ -1,5 +1,6 @@
 export * from './calendar.js';
 export * from './error-handling.js';
+export * from './edge-app-cache.js';
 export * from './html.js';
 export * from './theme.js';
 export * from './locale.js';

package/package.json

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