@use-voltra/ios-client 2.1.1 → 2.3.0

package/src/index.ts

@@ -5,6 +5,7 @@ export {
 } from './components/VoltraLiveActivityPreview.js'
 export { VoltraView, type VoltraViewProps } from './components/VoltraView.js'
 export { VoltraWidgetPreview, type VoltraWidgetPreviewProps } from './components/VoltraWidgetPreview.js'
+export { type DynamicWidgetProps, type DynamicWidgetPropsValue, updateDynamicWidget } from './dynamic-widget/api.js'
 export * from './events.js'
 export { isGlassSupported, isHeadless, useIsHeadless } from './helpers.js'
 export { logger, type VoltraLogLevel } from './logger.js'
@@ -22,6 +23,18 @@ export {
   type UseLiveActivityOptions,
   type UseLiveActivityResult,
 } from './live-activity/api.js'
+export {
+  getDynamicLiveActivityDefinitionIds,
+  startDynamicLiveActivity,
+  type StartDynamicLiveActivityOptions,
+  updateDynamicLiveActivity,
+  type UpdateDynamicLiveActivityOptions,
+  useDynamicLiveActivity,
+  type UseDynamicLiveActivityOptions,
+  type UseDynamicLiveActivityResult,
+  type DynamicLiveActivityProps,
+  type DynamicLiveActivityPropsValue,
+} from './live-activity/dynamic-api.js'
 export type { DismissalPolicy, LiveActivityVariants } from '@use-voltra/ios'
 export {
   clearPreloadedImages,
@@ -32,9 +45,19 @@ export {
 } from './preload.js'
 export { assertRunningOnApple } from './utils/assertRunningOnApple.js'
 export { enableWidgetHotReload } from './utils/enableWidgetHotReload.js'
+export { enableDynamicLiveActivityHotReload } from './utils/enableDynamicLiveActivityHotReload.js'
 export { useUpdateOnHMR } from './utils/useUpdateOnHMR.js'
 export * from './utils/helpers.js'
 export type { VoltraElementJson, VoltraNodeJson } from './types.js'
+export {
+  clearWidgetServerUpdate,
+  getWidgetServerUpdate,
+  setWidgetServerUpdate,
+  type WidgetServerUpdateBody,
+  type WidgetServerUpdateOptions,
+  type WidgetServerUpdateSettings,
+  type WidgetServerUpdateSnapshot,
+} from './widgets/server-update.js'
 export {
   clearWidgetServerCredentials,
   setWidgetServerCredentials,

package/src/live-activity/api.ts

@@ -40,7 +40,7 @@ export type UseLiveActivityResult = {
   isActive: boolean
 }
 
-const normalizeSharedLiveActivityOptions = (
+export const normalizeSharedLiveActivityOptions = (
   options?: SharedLiveActivityOptions
 ): SharedLiveActivityOptions | undefined => {
   if (!options) return undefined
@@ -66,7 +66,7 @@ const normalizeSharedLiveActivityOptions = (
   return Object.keys(normalizedOptions).length > 0 ? normalizedOptions : undefined
 }
 
-const normalizeEndLiveActivityOptions = (
+export const normalizeEndLiveActivityOptions = (
   options?: EndLiveActivityOptions
 ): { dismissalPolicy?: { type: 'immediate' | 'after'; date?: number } } | undefined => {
   if (!options?.dismissalPolicy) return undefined

package/src/live-activity/dynamic-api.ts

@@ -0,0 +1,240 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { addVoltraListener } from '../events.js'
+import { assertRunningOnApple, useUpdateOnHMR } from '../utils/index.js'
+import { getNativeVoltra } from '../VoltraModule.js'
+import {
+  isLiveActivityActive,
+  normalizeSharedLiveActivityOptions,
+  stopLiveActivity,
+  type EndLiveActivityOptions,
+  type SharedLiveActivityOptions,
+} from './api.js'
+
+/** @experimental A JSON-compatible value accepted as Dynamic Live Activity props. */
+export type DynamicLiveActivityPropsValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ReadonlyArray<DynamicLiveActivityPropsValue>
+  | Readonly<{ [key: string]: DynamicLiveActivityPropsValue }>
+
+/** @experimental A complete JSON-compatible props record for a Dynamic Live Activity update. */
+export type DynamicLiveActivityProps = Readonly<{ [key: string]: DynamicLiveActivityPropsValue }>
+
+/** @experimental Options used to start a Dynamic Live Activity. */
+export type StartDynamicLiveActivityOptions = {
+  activityName?: string
+  deepLinkUrl?: string
+  channelId?: string
+} & SharedLiveActivityOptions
+
+/** @experimental Options used to update a Dynamic Live Activity. */
+export type UpdateDynamicLiveActivityOptions = SharedLiveActivityOptions
+
+/** @experimental Options for `useDynamicLiveActivity`. */
+export type UseDynamicLiveActivityOptions = StartDynamicLiveActivityOptions & {
+  autoStart?: boolean
+  autoUpdate?: boolean
+}
+
+/** @experimental Lifecycle controls returned by `useDynamicLiveActivity`. */
+export type UseDynamicLiveActivityResult = {
+  start: (options?: StartDynamicLiveActivityOptions) => Promise<void>
+  update: (options?: UpdateDynamicLiveActivityOptions) => Promise<void>
+  end: (options?: EndLiveActivityOptions) => Promise<void>
+  isActive: boolean
+}
+
+function serializeDynamicLiveActivityProps(props: DynamicLiveActivityProps): string {
+  const ancestors = new Set<object>()
+
+  const validate = (value: unknown, path: string): void => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return
+
+    if (typeof value === 'number') {
+      if (!Number.isFinite(value)) {
+        throw new TypeError(`Dynamic Live Activity props must be JSON-compatible; ${path} is not a finite number.`)
+      }
+      return
+    }
+
+    if (Array.isArray(value)) {
+      if (ancestors.has(value)) {
+        throw new TypeError(
+          `Dynamic Live Activity props must be JSON-compatible; ${path} contains a circular reference.`
+        )
+      }
+      ancestors.add(value)
+      value.forEach((item, index) => validate(item, `${path}[${index}]`))
+      ancestors.delete(value)
+      return
+    }
+
+    if (typeof value === 'object') {
+      const prototype = Object.getPrototypeOf(value)
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError(`Dynamic Live Activity props must be JSON-compatible; ${path} must be a plain object.`)
+      }
+      if (ancestors.has(value)) {
+        throw new TypeError(
+          `Dynamic Live Activity props must be JSON-compatible; ${path} contains a circular reference.`
+        )
+      }
+      ancestors.add(value)
+      for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+        validate(item, `${path}.${key}`)
+      }
+      ancestors.delete(value)
+      return
+    }
+
+    throw new TypeError(
+      `Dynamic Live Activity props must be JSON-compatible; ${path} has unsupported type ${typeof value}.`
+    )
+  }
+
+  if (props === null || Array.isArray(props) || typeof props !== 'object') {
+    throw new TypeError('Dynamic Live Activity props must be a JSON-compatible record.')
+  }
+
+  validate(props, 'props')
+  return JSON.stringify(props)
+}
+
+/**
+ * Starts a bundled Dynamic Live Activity with a complete opaque props record.
+ * @experimental
+ */
+export async function startDynamicLiveActivity(
+  definitionId: string,
+  props: DynamicLiveActivityProps,
+  options?: StartDynamicLiveActivityOptions
+): Promise<string> {
+  if (!assertRunningOnApple()) return ''
+
+  const propsJson = serializeDynamicLiveActivityProps(props)
+  const normalizedSharedOptions = normalizeSharedLiveActivityOptions(options)
+  return getNativeVoltra().startDynamicLiveActivity(definitionId, propsJson, {
+    target: 'liveActivity',
+    deepLinkUrl: options?.deepLinkUrl,
+    activityName: options?.activityName,
+    channelId: options?.channelId,
+    ...normalizedSharedOptions,
+  })
+}
+
+/**
+ * Replaces a Dynamic Live Activity's complete opaque props record.
+ * @experimental
+ */
+export async function updateDynamicLiveActivity(
+  activityName: string,
+  props: DynamicLiveActivityProps,
+  options?: UpdateDynamicLiveActivityOptions
+): Promise<void> {
+  if (!assertRunningOnApple()) return
+
+  const propsJson = serializeDynamicLiveActivityProps(props)
+  return getNativeVoltra().updateDynamicLiveActivity(
+    activityName,
+    propsJson,
+    normalizeSharedLiveActivityOptions(options) ?? {}
+  )
+}
+
+/**
+ * Returns the Dynamic Live Activity definition IDs bundled in the installed app.
+ * @experimental
+ */
+export async function getDynamicLiveActivityDefinitionIds(): Promise<string[]> {
+  if (!assertRunningOnApple()) return []
+  return getNativeVoltra().getDynamicLiveActivityDefinitionIds()
+}
+
+/**
+ * Manages the lifecycle of one Dynamic Live Activity definition.
+ *
+ * Complete props are sent on every update. In development, call
+ * `enableDynamicLiveActivityHotReload()` once in the app host to reload only
+ * the definition changed by Fast Refresh.
+ * @experimental
+ */
+export function useDynamicLiveActivity<Props extends DynamicLiveActivityProps = DynamicLiveActivityProps>(
+  definitionId: string,
+  props: Props,
+  options?: UseDynamicLiveActivityOptions
+): UseDynamicLiveActivityResult {
+  const [activityName, setActivityName] = useState<string | null>(() => {
+    if (options?.activityName) {
+      return isLiveActivityActive(options.activityName) ? options.activityName : null
+    }
+    return null
+  })
+  const propsRef = useRef(props)
+  const optionsRef = useRef(options)
+  const lastUpdateOptionsRef = useRef<UpdateDynamicLiveActivityOptions | undefined>(undefined)
+
+  useEffect(() => {
+    propsRef.current = props
+  }, [props])
+
+  useEffect(() => {
+    optionsRef.current = options
+  }, [options])
+
+  useUpdateOnHMR()
+
+  const start = useCallback(
+    async (startOptions?: StartDynamicLiveActivityOptions) => {
+      const id = await startDynamicLiveActivity(definitionId, propsRef.current, {
+        ...optionsRef.current,
+        ...startOptions,
+      })
+      setActivityName(id)
+    },
+    [definitionId]
+  )
+
+  const update = useCallback(
+    async (updateOptions?: UpdateDynamicLiveActivityOptions) => {
+      if (!activityName) return
+
+      const mergedOptions = { ...optionsRef.current, ...updateOptions }
+      lastUpdateOptionsRef.current = mergedOptions
+      await updateDynamicLiveActivity(activityName, propsRef.current, mergedOptions)
+    },
+    [activityName]
+  )
+
+  const end = useCallback(
+    async (endOptions?: EndLiveActivityOptions) => {
+      if (!activityName) return
+
+      await stopLiveActivity(activityName, endOptions)
+      setActivityName(null)
+    },
+    [activityName]
+  )
+
+  useEffect(() => {
+    if (options?.autoStart) void start()
+  }, [options?.autoStart, start])
+
+  useEffect(() => {
+    if (options?.autoUpdate) void update(lastUpdateOptionsRef.current)
+  }, [options?.autoUpdate, props, update])
+
+  useEffect(() => {
+    if (!activityName) return
+
+    const subscription = addVoltraListener('stateChange', (event) => {
+      if (event.activityName !== activityName) return
+      if (event.activityState === 'dismissed' || event.activityState === 'ended') setActivityName(null)
+    })
+    return () => subscription.remove()
+  }, [activityName])
+
+  return { start, update, end, isActive: activityName !== null }
+}

package/src/native/NativeVoltra.ts

@@ -32,6 +32,15 @@ type VoltraInteractionEvent = Readonly<{
   payload: string
 }>
 
+type VoltraDynamicLiveActivityRenderFailedEvent = Readonly<{
+  source: string
+  timestamp: number
+  type: 'dynamicLiveActivityRenderFailed'
+  activityName: string
+  definitionId: string
+  message: string
+}>
+
 type StartVoltraOptions = Readonly<{
   target?: string
   deepLinkUrl?: string
@@ -86,26 +95,39 @@ type WidgetServerCredentials = Readonly<{
 
 export interface Spec extends TurboModule {
   readonly onInteraction: CodegenTypes.EventEmitter<VoltraInteractionEvent>
+  readonly onDynamicLiveActivityRenderFailed: CodegenTypes.EventEmitter<VoltraDynamicLiveActivityRenderFailedEvent>
   readonly onStateChanged: CodegenTypes.EventEmitter<VoltraActivityUpdateEvent>
   readonly onActivityTokenReceived: CodegenTypes.EventEmitter<VoltraActivityTokenReceivedEvent>
   readonly onActivityPushToStartTokenReceived: CodegenTypes.EventEmitter<VoltraActivityPushToStartTokenReceivedEvent>
+  drainDynamicLiveActivityRenderFailures(): void
+  setDynamicLiveActivityRenderFailureListenerActive(active: boolean): void
   startLiveActivity(jsonString: string, options: StartVoltraOptions): Promise<string>
   updateLiveActivity(activityId: string, jsonString: string, options: UpdateVoltraOptions): Promise<void>
+  startDynamicLiveActivity(definitionId: string, propsJson: string, options: StartVoltraOptions): Promise<string>
+  updateDynamicLiveActivity(activityId: string, propsJson: string, options: UpdateVoltraOptions): Promise<void>
   endLiveActivity(activityId: string, options: EndVoltraOptions): Promise<void>
   endAllLiveActivities(): Promise<void>
   getLatestVoltraActivityId(): Promise<string | null>
   listVoltraActivityIds(): Promise<string[]>
+  getDynamicLiveActivityDefinitionIds(): Promise<string[]>
   isLiveActivityActive(activityName: string): boolean
   isHeadless(): boolean
   preloadImages(images: PreloadImageOptions[]): Promise<PreloadImagesResult>
   reloadLiveActivities(activityNames?: string[] | null): Promise<void>
+  reloadDynamicLiveActivities(definitionIds?: string[] | null): Promise<void>
   clearPreloadedImages(keys?: string[] | null): Promise<void>
+  updateDynamicWidget(dynamicWidgetId: string, dynamicWidgetPropsJson: string): Promise<void>
   updateWidget(widgetId: string, jsonString: string, options: UpdateWidgetOptions): Promise<void>
   scheduleWidget(widgetId: string, timelineJson: string): Promise<void>
   reloadWidgets(widgetIds?: string[] | null): Promise<void>
   clearWidget(widgetId: string): Promise<void>
   clearAllWidgets(): Promise<void>
   getActiveWidgets<T = unknown>(): Promise<T[]>
+  /** Settings are passed as JSON so an arbitrary `body` survives the bridge unchanged. */
+  setWidgetServerUpdate(settingsJson: string, widgetId?: string | null): Promise<void>
+  clearWidgetServerUpdate(widgetId?: string | null): Promise<void>
+  /** Result is JSON so an arbitrary `body` survives the bridge unchanged, or null. */
+  getWidgetServerUpdate(widgetId?: string | null): Promise<string | null>
   setWidgetServerCredentials(credentials: WidgetServerCredentials): Promise<void>
   clearWidgetServerCredentials(): Promise<void>
 }

package/src/types.ts

@@ -9,4 +9,8 @@ export type {
   VoltraNodeJson,
   VoltraPropValue,
   WidgetServerCredentials,
+  WidgetServerUpdateBody,
+  WidgetServerUpdateOptions,
+  WidgetServerUpdateSettings,
+  WidgetServerUpdateSnapshot,
 } from '@use-voltra/ios'

package/src/utils/enableDynamicLiveActivityHotReload.ts

@@ -0,0 +1,50 @@
+import { getFastRefreshHub } from '@use-voltra/ios'
+
+import { getNativeVoltra } from '../VoltraModule.js'
+
+declare global {
+  var __voltraDynamicLiveActivityDefinitionUpdated: ((definitionId: string) => void) | undefined
+}
+
+/**
+ * Reload Dynamic Live Activities after a Metro Fast Refresh patch. When Metro
+ * re-evaluates a generated definition entry, only that definition is reloaded.
+ * Component-only refresh boundaries do not re-evaluate their importer, so those
+ * patches fall back to reloading every Dynamic Live Activity definition.
+ * Legacy activities and Dynamic Widgets are unaffected.
+ *
+ * Subscribes to the shared {@link getFastRefreshHub} so multiple `__accept`
+ * calls from one save collapse into a single native reload.
+ */
+export function enableDynamicLiveActivityHotReload(): () => void {
+  if (!__DEV__) return () => {}
+
+  const hub = getFastRefreshHub()
+  const previousDefinitionUpdated = global.__voltraDynamicLiveActivityDefinitionUpdated
+  const updatedDefinitionIds = new Set<string>()
+
+  global.__voltraDynamicLiveActivityDefinitionUpdated = (definitionId) => {
+    // A generated entry re-evaluated inside a patch: batch it so the debounced
+    // flush reloads each changed definition exactly once. A signal that arrives
+    // outside a patch (the first require of a definition) has no flush coming,
+    // so reload it immediately.
+    if (hub.isAccepting) {
+      updatedDefinitionIds.add(definitionId)
+      return
+    }
+    void getNativeVoltra().reloadDynamicLiveActivities([definitionId])
+  }
+
+  const unsubscribe = hub.onPatch(() => {
+    const definitionIds = Array.from(updatedDefinitionIds)
+    updatedDefinitionIds.clear()
+    // No definition re-evaluated during this patch: a component-only boundary
+    // changed, so fall back to reloading every definition (null).
+    void getNativeVoltra().reloadDynamicLiveActivities(definitionIds.length > 0 ? definitionIds : null)
+  })
+
+  return () => {
+    unsubscribe()
+    global.__voltraDynamicLiveActivityDefinitionUpdated = previousDefinitionUpdated
+  }
+}

package/src/utils/enableWidgetHotReload.ts

@@ -1,14 +1,13 @@
-import { reloadWidgets } from '../widgets/widget-api.js'
+import { getFastRefreshHub } from '@use-voltra/ios'
 
-declare global {
-  var __accept: (...args: unknown[]) => void
-}
+import { reloadWidgets } from '../widgets/widget-api.js'
 
 /**
  * Trigger `reloadWidgets()` on every Metro Fast Refresh patch (DEV only).
  *
- * Hooks the global `__accept` callback Metro fires when a Fast Refresh patch
- * lands in the host app's JS runtime. When fired, calls
+ * Subscribes to the shared {@link getFastRefreshHub}, which wraps the global
+ * `__accept` callback Metro fires when a Fast Refresh patch lands in the host
+ * app's JS runtime. On each debounced patch it calls
  * `WidgetCenter.shared.reloadAllTimelines()` so WidgetKit re-invokes each widget
  * Provider, which re-fetches the freshest bundle from Metro and renders the
  * updated UI.
@@ -19,21 +18,15 @@ declare global {
  * workflow the dev still relies on WidgetKit's natural lifecycle refresh on
  * app foreground.
  *
- * Call once at app startup. Returns `dispose()` to restore the prior
- * `__accept` (rarely needed in practice). No-op in release builds.
+ * Call once at app startup. Returns `dispose()` to unsubscribe (rarely needed
+ * in practice). No-op in release builds.
  */
 export function enableWidgetHotReload(): () => void {
   if (!__DEV__) {
     return () => {}
   }
 
-  const oldAccept = global['__accept']
-  global['__accept'] = (...args) => {
+  return getFastRefreshHub().onPatch(() => {
     void reloadWidgets()
-    oldAccept?.(...args)
-  }
-
-  return () => {
-    global['__accept'] = oldAccept
-  }
+  })
 }

package/src/utils/useUpdateOnHMR.ts

@@ -1,9 +1,6 @@
+import { getFastRefreshHub } from '@use-voltra/ios'
 import { useEffect, useState } from 'react'
 
-declare global {
-  var __accept: (...args: unknown[]) => void
-}
-
 export const useUpdateOnHMR = () => {
   const [, forceUpdate] = useState(0)
 
@@ -12,14 +9,8 @@ export const useUpdateOnHMR = () => {
       return
     }
 
-    const oldAccept = global['__accept']
-    global['__accept'] = (...args) => {
+    return getFastRefreshHub().onPatch(() => {
       forceUpdate((prev) => prev + 1)
-      oldAccept?.(...args)
-    }
-
-    return () => {
-      global['__accept'] = oldAccept
-    }
+    })
   }, [])
 }

package/src/widgets/server-credentials.ts

@@ -3,6 +3,11 @@ import { getNativeVoltra } from '../VoltraModule.js'
 
 export type { WidgetServerCredentials } from '../types.js'
 
+/**
+ * @deprecated Use {@link setWidgetServerUpdate} with an `Authorization` header. This writes the
+ * same stored credentials and keeps the same replace-everything semantics, so migrating is a
+ * one-line change; it will be removed in a future major.
+ */
 export async function setWidgetServerCredentials(credentials: WidgetServerCredentials): Promise<void> {
   if (!credentials.token) {
     throw new Error('[Voltra][iOS] setWidgetServerCredentials: token is required')
@@ -11,6 +16,9 @@ export async function setWidgetServerCredentials(credentials: WidgetServerCreden
   return getNativeVoltra().setWidgetServerCredentials(credentials)
 }
 
+/**
+ * @deprecated Use {@link clearWidgetServerUpdate} instead.
+ */
 export async function clearWidgetServerCredentials(): Promise<void> {
   return getNativeVoltra().clearWidgetServerCredentials()
 }

package/src/widgets/server-update.ts

@@ -0,0 +1,84 @@
+import type { WidgetServerUpdateOptions, WidgetServerUpdateSettings, WidgetServerUpdateSnapshot } from '../types.js'
+import { getNativeVoltra } from '../VoltraModule.js'
+
+export type {
+  WidgetServerUpdateBody,
+  WidgetServerUpdateOptions,
+  WidgetServerUpdateSettings,
+  WidgetServerUpdateSnapshot,
+} from '../types.js'
+
+/**
+ * Overrides a server-driven widget's `serverUpdate` settings at runtime.
+ *
+ * The `serverUpdate` entry in app.json supplies the defaults; this replaces any of them for one
+ * widget, or for every server-driven widget when no `widgetId` is given. A widget-scoped call wins
+ * over a global one, and `headers` and `query` merge per key across the two.
+ *
+ * Each call replaces the whole layer it writes, so pass every field you want to keep. Setting
+ * anything reschedules the widgets it affects and fetches once immediately.
+ *
+ * @example Point a widget at the tenant's own backend once the user has logged in.
+ * ```ts
+ * await setWidgetServerUpdate(
+ *   { url: `https://${tenant}.example.com/widgets/portfolio`, headers: { Authorization: `Bearer ${token}` } },
+ *   { widgetId: 'portfolio' }
+ * )
+ * ```
+ *
+ * @example Take a widget over and drive it from the app until you hand it back.
+ * ```ts
+ * await setWidgetServerUpdate({ enabled: false }, { widgetId: 'portfolio' })
+ * await updateDynamicWidget('portfolio', localProps)
+ * ```
+ *
+ * @throws if the widget has no `serverUpdate` in app.json, if the URL is not https (plain http is
+ *   allowed only in a debug build, and only for a local dev host), or if `query` names one of the
+ *   parameters Voltra already sends.
+ */
+export async function setWidgetServerUpdate(
+  settings: WidgetServerUpdateSettings,
+  options?: WidgetServerUpdateOptions
+): Promise<void> {
+  return getNativeVoltra().setWidgetServerUpdate(JSON.stringify(settings ?? {}), options?.widgetId ?? null)
+}
+
+/**
+ * Drops the runtime settings for one widget, or the global ones when no `widgetId` is given, so
+ * the widget falls back to what app.json configured.
+ *
+ * Clearing the global settings is the logout gesture: along with the settings it drops what the
+ * server last sent for every server-driven widget, so a Dynamic Widget goes back to `{}` with
+ * `env.serverUpdate.status` of `never` rather than showing the previous account's data. Credentials
+ * set with the deprecated `setWidgetServerCredentials` are stored separately — clear those with
+ * `clearWidgetServerCredentials`.
+ */
+export async function clearWidgetServerUpdate(options?: WidgetServerUpdateOptions): Promise<void> {
+  return getNativeVoltra().clearWidgetServerUpdate(options?.widgetId ?? null)
+}
+
+/**
+ * Reads a widget's `serverUpdate` settings back, without reasoning about what was set where.
+ *
+ * With a `widgetId`, this is the fully resolved settings that widget would fetch with right now:
+ * every layer flattened and app.json's defaults applied — `null` if the widget is not
+ * server-driven. Without one, this is the raw contents of the global layer only — what the last
+ * `setWidgetServerUpdate(settings)` call (with no `widgetId`) wrote, with no defaults applied and
+ * every field optional — `null` if nothing has been set globally.
+ *
+ * @example Check what a widget is about to fetch from.
+ * ```ts
+ * const snapshot = await getWidgetServerUpdate({ widgetId: 'portfolio' })
+ * if (snapshot?.enabled) {
+ *   console.log(`portfolio fetches ${snapshot.url} every ${snapshot.intervalMinutes}m`)
+ * }
+ * ```
+ */
+export async function getWidgetServerUpdate(options: { widgetId: string }): Promise<WidgetServerUpdateSnapshot | null>
+export async function getWidgetServerUpdate(options?: undefined): Promise<WidgetServerUpdateSettings | null>
+export async function getWidgetServerUpdate(
+  options?: WidgetServerUpdateOptions
+): Promise<WidgetServerUpdateSnapshot | WidgetServerUpdateSettings | null> {
+  const json = await getNativeVoltra().getWidgetServerUpdate(options?.widgetId ?? null)
+  return json == null ? null : JSON.parse(json)
+}