@use-voltra/ios-client 2.0.0-rc.1 → 2.0.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-voltra/ios-client",
-  "version": "2.0.0-rc.1",
+  "version": "2.0.0-rc.2",
   "description": "Client-only Voltra APIs for iOS",
   "main": "./build/commonjs/index.js",
   "module": "./build/module/index.js",
@@ -25,9 +25,22 @@
     "build",
     "expo-plugin",
     "ios",
+    "src",
     "!ios/.build",
     "Voltra.podspec",
-    "README.md"
+    "README.md",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
   ],
   "scripts": {
     "build": "npm run clean && npm run build:expo-plugin && bob build",
@@ -47,8 +60,8 @@
     "@babel/core": "^7.27.4",
     "@expo/config-plugins": "~10.1.2",
     "@expo/plist": "^0.3.5",
-    "@use-voltra/expo-plugin": "2.0.0-rc.1",
-    "@use-voltra/ios": "2.0.0-rc.1",
+    "@use-voltra/expo-plugin": "2.0.0-rc.2",
+    "@use-voltra/ios": "2.0.0-rc.2",
     "dedent": "^1.7.1",
     "xcode": "^3.0.1"
   },

package/src/VoltraModule.ts

@@ -0,0 +1,2 @@
+export type { Spec as VoltraIOSModuleSpec } from './native/NativeVoltra'
+export { getNativeVoltra } from './native/NativeVoltra'

package/src/components/VoltraLiveActivityPreview.tsx

@@ -0,0 +1,29 @@
+import React from 'react'
+import { type StyleProp, type ViewStyle } from 'react-native'
+
+import { VoltraView, type VoltraViewProps } from './VoltraView.js'
+
+const LOCK_SCREEN_DIMENSIONS = {
+  width: 364,
+  height: 160,
+}
+
+export type VoltraLiveActivityPreviewProps = Omit<VoltraViewProps, 'style'> & {
+  style?: StyleProp<ViewStyle>
+}
+
+export function VoltraLiveActivityPreview({ style, children, ...voltraViewProps }: VoltraLiveActivityPreviewProps) {
+  const previewStyle: StyleProp<ViewStyle> = [
+    {
+      width: LOCK_SCREEN_DIMENSIONS.width,
+      height: LOCK_SCREEN_DIMENSIONS.height,
+    },
+    style,
+  ]
+
+  return (
+    <VoltraView {...voltraViewProps} style={previewStyle}>
+      {children}
+    </VoltraView>
+  )
+}

package/src/components/VoltraView.tsx

@@ -0,0 +1,49 @@
+import React, { type ReactNode, useEffect, useMemo } from 'react'
+import { type StyleProp, type ViewStyle } from 'react-native'
+
+import { renderVoltraVariantToJson } from '@use-voltra/ios'
+
+import VoltraFabricView from '../native/VoltraRNNativeComponent'
+
+import { addVoltraListener, type VoltraInteractionEvent } from '../events.js'
+
+const generateViewId = () => `voltra-view-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
+
+const voltraViewStyle: ViewStyle = {
+  flex: 1,
+}
+
+export type VoltraViewProps = {
+  id?: string
+  children: ReactNode
+  style?: StyleProp<ViewStyle>
+  onInteraction?: (event: VoltraInteractionEvent) => void
+  testID?: string
+}
+
+export function VoltraView({ id, children, style, onInteraction, testID }: VoltraViewProps) {
+  const viewId = useMemo(() => id || generateViewId(), [id])
+
+  const json = renderVoltraVariantToJson(children)
+  const payload = JSON.stringify(json)
+
+  useEffect(() => {
+    if (!onInteraction) return
+
+    const subscription = addVoltraListener('interaction', (event) => {
+      if (event.source === viewId) {
+        onInteraction({
+          type: 'interaction',
+          source: event.source,
+          timestamp: event.timestamp,
+          identifier: event.identifier,
+          payload: event.payload,
+        })
+      }
+    })
+
+    return () => subscription.remove()
+  }, [viewId, onInteraction])
+
+  return <VoltraFabricView payload={payload} style={[voltraViewStyle, style]} testID={testID} viewId={viewId} />
+}

package/src/components/VoltraWidgetPreview.tsx

@@ -0,0 +1,38 @@
+import React from 'react'
+import { type StyleProp, type ViewStyle } from 'react-native'
+
+import type { WidgetFamily } from '@use-voltra/ios'
+
+import { VoltraView, type VoltraViewProps } from './VoltraView.js'
+
+const WIDGET_DIMENSIONS: Record<WidgetFamily, { width: number; height: number }> = {
+  systemSmall: { width: 170, height: 170 },
+  systemMedium: { width: 364, height: 170 },
+  systemLarge: { width: 364, height: 382 },
+  systemExtraLarge: { width: 364, height: 768 },
+  accessoryCircular: { width: 76, height: 76 },
+  accessoryRectangular: { width: 172, height: 76 },
+  accessoryInline: { width: 172, height: 40 },
+}
+
+export type VoltraWidgetPreviewProps = Omit<VoltraViewProps, 'style'> & {
+  family: WidgetFamily
+  style?: StyleProp<ViewStyle>
+}
+
+export function VoltraWidgetPreview({ family, style, children, ...voltraViewProps }: VoltraWidgetPreviewProps) {
+  const dimensions = WIDGET_DIMENSIONS[family]
+  const previewStyle: StyleProp<ViewStyle> = [
+    {
+      width: dimensions.width,
+      height: dimensions.height,
+    },
+    style,
+  ]
+
+  return (
+    <VoltraView {...voltraViewProps} style={previewStyle}>
+      {children}
+    </VoltraView>
+  )
+}

package/src/events.ts

@@ -0,0 +1,70 @@
+import { Platform } from 'react-native'
+
+import type { EventSubscription } from './types.js'
+import { getNativeVoltra } from './VoltraModule.js'
+
+export type BasicVoltraEvent = {
+  source: string
+  timestamp: number
+}
+
+export type VoltraActivityState = 'active' | 'dismissed' | 'pending' | 'stale' | 'ended' | string
+export type VoltraActivityTokenReceivedEvent = BasicVoltraEvent & {
+  type: 'activityTokenReceived'
+  activityName: string
+  pushToken: string
+}
+export type VoltraActivityPushToStartTokenReceivedEvent = BasicVoltraEvent & {
+  type: 'activityPushToStartTokenReceived'
+  pushToStartToken: string
+}
+export type VoltraActivityUpdateEvent = BasicVoltraEvent & {
+  type: 'stateChange'
+  activityName: string
+  activityState: VoltraActivityState
+}
+
+export type VoltraInteractionEvent = BasicVoltraEvent & {
+  type: 'interaction'
+  identifier: string
+  payload: string
+}
+
+const noopSubscription: EventSubscription = {
+  remove: () => {},
+}
+
+export type VoltraEventMap = {
+  activityTokenReceived: VoltraActivityTokenReceivedEvent
+  activityPushToStartTokenReceived: VoltraActivityPushToStartTokenReceivedEvent
+  stateChange: VoltraActivityUpdateEvent
+  interaction: VoltraInteractionEvent
+}
+
+export function addVoltraListener<K extends keyof VoltraEventMap>(
+  event: K,
+  listener: (event: VoltraEventMap[K]) => void
+): EventSubscription {
+  if (Platform.OS !== 'ios') {
+    console.warn(`[Voltra] Event '${event}' is only supported on iOS. Returning no-op subscription.`)
+    return noopSubscription
+  }
+
+  const voltraModule = getNativeVoltra()
+
+  switch (event) {
+    case 'activityTokenReceived':
+      return voltraModule.onActivityTokenReceived(listener as (arg: VoltraActivityTokenReceivedEvent) => void)
+    case 'activityPushToStartTokenReceived':
+      return voltraModule.onActivityPushToStartTokenReceived(
+        listener as (arg: VoltraActivityPushToStartTokenReceivedEvent) => void
+      )
+    case 'stateChange':
+      return voltraModule.onStateChanged(listener as (arg: VoltraActivityUpdateEvent) => void)
+    case 'interaction':
+      return voltraModule.onInteraction(listener as (arg: VoltraInteractionEvent) => void)
+    default:
+      console.warn(`[Voltra] Event '${event}' is not supported. Returning no-op subscription.`)
+      return noopSubscription
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,21 @@
+import { Platform } from 'react-native'
+
+import { getNativeVoltra } from './VoltraModule.js'
+
+export function isGlassSupported(): boolean {
+  if (Platform.OS !== 'ios') return false
+  const v: any = Platform.Version
+  let major = 0
+  if (typeof v === 'string') {
+    const m = parseInt(v.split('.')[0] || '0', 10)
+    if (!Number.isNaN(m)) major = m
+  } else if (typeof v === 'number') {
+    major = Math.floor(v)
+  }
+  return major >= 26
+}
+
+export function isHeadless(): boolean {
+  if (Platform.OS !== 'ios') return false
+  return getNativeVoltra().isHeadless?.() ?? false
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+export { Voltra } from '@use-voltra/ios'
+export {
+  VoltraLiveActivityPreview,
+  type VoltraLiveActivityPreviewProps,
+} from './components/VoltraLiveActivityPreview.js'
+export { VoltraView, type VoltraViewProps } from './components/VoltraView.js'
+export { VoltraWidgetPreview, type VoltraWidgetPreviewProps } from './components/VoltraWidgetPreview.js'
+export * from './events.js'
+export { isGlassSupported, isHeadless } from './helpers.js'
+export { logger, type VoltraLogLevel } from './logger.js'
+export {
+  endAllLiveActivities,
+  type EndLiveActivityOptions,
+  isLiveActivityActive,
+  type SharedLiveActivityOptions,
+  startLiveActivity,
+  type StartLiveActivityOptions,
+  stopLiveActivity,
+  updateLiveActivity,
+  type UpdateLiveActivityOptions,
+  useLiveActivity,
+  type UseLiveActivityOptions,
+  type UseLiveActivityResult,
+} from './live-activity/api.js'
+export type { DismissalPolicy, LiveActivityVariants } from '@use-voltra/ios'
+export {
+  clearPreloadedImages,
+  type PreloadImageOptions,
+  preloadImages,
+  type PreloadImagesResult,
+  reloadLiveActivities,
+} from './preload.js'
+export { assertRunningOnApple } from './utils/assertRunningOnApple.js'
+export { useUpdateOnHMR } from './utils/useUpdateOnHMR.js'
+export * from './utils/helpers.js'
+export type { VoltraElementJson, VoltraNodeJson } from './types.js'
+export {
+  clearWidgetServerCredentials,
+  setWidgetServerCredentials,
+  type WidgetServerCredentials,
+} from './widgets/server-credentials.js'
+export type { WidgetFamily, WidgetInfo, WidgetVariants } from '@use-voltra/ios'
+export {
+  clearAllWidgets,
+  clearWidget,
+  getActiveWidgets,
+  reloadWidgets,
+  type ScheduledWidgetEntry,
+  scheduleWidget,
+  updateWidget,
+  type UpdateWidgetOptions,
+} from './widgets/widget-api.js'

package/src/live-activity/api.ts

@@ -0,0 +1,224 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { renderLiveActivityToString, type DismissalPolicy, type LiveActivityVariants } from '@use-voltra/ios'
+
+import { addVoltraListener } from '../events.js'
+import { logger } from '../logger.js'
+import { assertRunningOnApple, useUpdateOnHMR } from '../utils/index.js'
+import { getNativeVoltra } from '../VoltraModule.js'
+
+export type SharedLiveActivityOptions = {
+  staleDate?: number
+  relevanceScore?: number
+  dismissalPolicy?: DismissalPolicy
+}
+
+export type StartLiveActivityOptions = {
+  activityName?: string
+  deepLinkUrl?: string
+  channelId?: string
+} & SharedLiveActivityOptions
+
+export type UpdateLiveActivityOptions = SharedLiveActivityOptions
+
+export type EndLiveActivityOptions = {
+  dismissalPolicy?: DismissalPolicy
+}
+
+export type UseLiveActivityOptions = {
+  activityName?: string
+  autoStart?: boolean
+  autoUpdate?: boolean
+  deepLinkUrl?: string
+  channelId?: string
+}
+
+export type UseLiveActivityResult = {
+  start: (options?: StartLiveActivityOptions) => Promise<void>
+  update: (options?: UpdateLiveActivityOptions) => Promise<void>
+  end: (options?: EndLiveActivityOptions) => Promise<void>
+  isActive: boolean
+}
+
+const normalizeSharedLiveActivityOptions = (
+  options?: SharedLiveActivityOptions
+): SharedLiveActivityOptions | undefined => {
+  if (!options) return undefined
+
+  const normalizedOptions: SharedLiveActivityOptions = {}
+
+  if (options.staleDate !== undefined) {
+    if (options.staleDate < Date.now()) {
+      logger.warn('Ignoring staleDate because it is in the past, the Live Activity would be dismissed immediately.')
+    } else {
+      normalizedOptions.staleDate = options.staleDate
+    }
+  }
+
+  const relevanceScore = options.relevanceScore ?? 0.0
+  if (relevanceScore < 0 || relevanceScore > 1) {
+    logger.warn('Ignoring relevanceScore because it is out of range [0.0, 1.0], using default 0.0')
+    normalizedOptions.relevanceScore = 0.0
+  } else {
+    normalizedOptions.relevanceScore = relevanceScore
+  }
+
+  return Object.keys(normalizedOptions).length > 0 ? normalizedOptions : undefined
+}
+
+const normalizeEndLiveActivityOptions = (
+  options?: EndLiveActivityOptions
+): { dismissalPolicy?: { type: 'immediate' | 'after'; date?: number } } | undefined => {
+  if (!options?.dismissalPolicy) return undefined
+
+  if (typeof options.dismissalPolicy === 'string') {
+    if (options.dismissalPolicy === 'immediate') {
+      return { dismissalPolicy: { type: 'immediate' } }
+    }
+  } else if (typeof options.dismissalPolicy === 'object' && 'after' in options.dismissalPolicy) {
+    return { dismissalPolicy: { type: 'after', date: options.dismissalPolicy.after } }
+  }
+
+  return { dismissalPolicy: { type: 'immediate' } }
+}
+
+export const useLiveActivity = (
+  variants: LiveActivityVariants,
+  options?: UseLiveActivityOptions
+): UseLiveActivityResult => {
+  const [targetId, setTargetId] = useState<string | null>(() => {
+    if (options?.activityName) {
+      return isLiveActivityActive(options.activityName) ? options.activityName : null
+    }
+
+    return null
+  })
+  const isActive = targetId !== null
+  const optionsRef = useRef(options)
+  const variantsRef = useRef(variants)
+  const lastUpdateOptionsRef = useRef<UpdateLiveActivityOptions | undefined>(undefined)
+
+  useEffect(() => {
+    optionsRef.current = options
+  }, [options])
+
+  useEffect(() => {
+    variantsRef.current = variants
+  }, [variants])
+
+  useUpdateOnHMR()
+
+  const start = useCallback(async (options?: StartLiveActivityOptions) => {
+    const id = await startLiveActivity(variantsRef.current, { ...optionsRef.current, ...options })
+    setTargetId(id)
+  }, [])
+
+  const update = useCallback(
+    async (options?: UpdateLiveActivityOptions) => {
+      if (!targetId) {
+        return
+      }
+
+      const updateOptions = { ...optionsRef.current, ...options }
+      lastUpdateOptionsRef.current = updateOptions
+      await updateLiveActivity(targetId, variantsRef.current, updateOptions)
+    },
+    [targetId]
+  )
+
+  const end = useCallback(
+    async (options?: EndLiveActivityOptions) => {
+      if (!targetId) {
+        return
+      }
+
+      await stopLiveActivity(targetId, options)
+      setTargetId(null)
+    },
+    [targetId]
+  )
+
+  useEffect(() => {
+    if (!options?.autoStart) {
+      return
+    }
+
+    start()
+  }, [options?.autoStart, start])
+
+  useEffect(() => {
+    if (!options?.autoUpdate) return
+    update(lastUpdateOptionsRef.current)
+  }, [options?.autoUpdate, update, variants])
+
+  useEffect(() => {
+    if (!targetId) return
+
+    const subscription = addVoltraListener('stateChange', (event) => {
+      if (event.activityName !== targetId) return
+
+      if (event.activityState === 'dismissed' || event.activityState === 'ended') {
+        setTargetId(null)
+      }
+    })
+
+    return () => subscription.remove()
+  }, [targetId])
+
+  return {
+    start,
+    update,
+    end,
+    isActive,
+  }
+}
+
+export const startLiveActivity = async (
+  variants: LiveActivityVariants,
+  options?: StartLiveActivityOptions
+): Promise<string> => {
+  if (!assertRunningOnApple()) return Promise.resolve('')
+
+  const payload = renderLiveActivityToString(variants)
+
+  const normalizedSharedOptions = normalizeSharedLiveActivityOptions(options)
+  const targetId = await getNativeVoltra().startLiveActivity(payload, {
+    target: 'liveActivity',
+    deepLinkUrl: options?.deepLinkUrl,
+    activityName: options?.activityName,
+    channelId: options?.channelId,
+    ...normalizedSharedOptions,
+  })
+  return targetId
+}
+
+export const updateLiveActivity = async (
+  targetId: string,
+  variants: LiveActivityVariants,
+  options?: UpdateLiveActivityOptions
+): Promise<void> => {
+  if (!assertRunningOnApple()) return Promise.resolve()
+
+  const payload = renderLiveActivityToString(variants)
+
+  const normalizedSharedOptions = normalizeSharedLiveActivityOptions(options)
+  return getNativeVoltra().updateLiveActivity(targetId, payload, normalizedSharedOptions ?? {})
+}
+
+export const stopLiveActivity = async (targetId: string, options?: EndLiveActivityOptions): Promise<void> => {
+  if (!assertRunningOnApple()) return Promise.resolve()
+
+  const normalizedOptions = normalizeEndLiveActivityOptions(options)
+  return getNativeVoltra().endLiveActivity(targetId, normalizedOptions ?? { dismissalPolicy: { type: 'immediate' } })
+}
+
+export const isLiveActivityActive = (activityName: string): boolean => {
+  if (!assertRunningOnApple()) return false
+
+  return getNativeVoltra().isLiveActivityActive(activityName)
+}
+
+export async function endAllLiveActivities(): Promise<void> {
+  if (!assertRunningOnApple()) return Promise.resolve()
+  return getNativeVoltra().endAllLiveActivities()
+}

package/src/logger.ts

@@ -0,0 +1,35 @@
+const LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+} as const
+export type VoltraLogLevel = keyof typeof LEVELS
+
+let currentLevel: VoltraLogLevel = __DEV__ ? 'debug' : 'info'
+
+export const logger = {
+  debug: (message: string) => {
+    if (LEVELS.debug >= LEVELS[currentLevel]) {
+      console.log(`[Voltra] ${message}`)
+    }
+  },
+  info: (message: string) => {
+    if (LEVELS.info >= LEVELS[currentLevel]) {
+      console.info(`[Voltra] ${message}`)
+    }
+  },
+  warn: (message: string) => {
+    if (LEVELS.warn >= LEVELS[currentLevel]) {
+      console.warn(`[Voltra] ${message}`)
+    }
+  },
+  error: (message: string) => {
+    if (LEVELS.error >= LEVELS[currentLevel]) {
+      console.error(`[Voltra] ${message}`)
+    }
+  },
+  setLevel: (level: VoltraLogLevel) => {
+    currentLevel = level
+  },
+}

package/src/native/NativeVoltra.ts

@@ -0,0 +1,118 @@
+import type { CodegenTypes, TurboModule } from 'react-native'
+import { TurboModuleRegistry } from 'react-native'
+
+type VoltraActivityTokenReceivedEvent = Readonly<{
+  source: string
+  timestamp: number
+  type: 'activityTokenReceived'
+  activityName: string
+  pushToken: string
+}>
+
+type VoltraActivityPushToStartTokenReceivedEvent = Readonly<{
+  source: string
+  timestamp: number
+  type: 'activityPushToStartTokenReceived'
+  pushToStartToken: string
+}>
+
+type VoltraActivityUpdateEvent = Readonly<{
+  source: string
+  timestamp: number
+  type: 'stateChange'
+  activityName: string
+  activityState: string
+}>
+
+type VoltraInteractionEvent = Readonly<{
+  source: string
+  timestamp: number
+  type: 'interaction'
+  identifier: string
+  payload: string
+}>
+
+type StartVoltraOptions = Readonly<{
+  target?: string
+  deepLinkUrl?: string
+  activityName?: string
+  staleDate?: number
+  relevanceScore?: number
+  channelId?: string
+}>
+
+type UpdateVoltraOptions = Readonly<{
+  staleDate?: number
+  relevanceScore?: number
+}>
+
+type DismissalPolicyOptions = Readonly<{
+  type: string
+  date?: number
+}>
+
+type EndVoltraOptions = Readonly<{
+  dismissalPolicy?: DismissalPolicyOptions
+}>
+
+type UpdateWidgetOptions = Readonly<{
+  deepLinkUrl?: string
+}>
+
+type PreloadImageOptions = Readonly<{
+  url: string
+  key: string
+  method?: string
+  headers?: Readonly<{ [key: string]: string }>
+}>
+
+type PreloadImageFailure = Readonly<{
+  key: string
+  error: string
+}>
+
+type PreloadImagesResult = Readonly<{
+  succeeded: string[]
+  failed: PreloadImageFailure[]
+}>
+
+type WidgetServerCredentials = Readonly<{
+  token: string
+  headers?: Readonly<{ [key: string]: string }>
+}>
+
+export interface Spec extends TurboModule {
+  readonly onInteraction: CodegenTypes.EventEmitter<VoltraInteractionEvent>
+  readonly onStateChanged: CodegenTypes.EventEmitter<VoltraActivityUpdateEvent>
+  readonly onActivityTokenReceived: CodegenTypes.EventEmitter<VoltraActivityTokenReceivedEvent>
+  readonly onActivityPushToStartTokenReceived: CodegenTypes.EventEmitter<VoltraActivityPushToStartTokenReceivedEvent>
+  startLiveActivity(jsonString: string, options: StartVoltraOptions): Promise<string>
+  updateLiveActivity(activityId: string, jsonString: string, options: UpdateVoltraOptions): Promise<void>
+  endLiveActivity(activityId: string, options: EndVoltraOptions): Promise<void>
+  endAllLiveActivities(): Promise<void>
+  getLatestVoltraActivityId(): Promise<string | null>
+  listVoltraActivityIds(): Promise<string[]>
+  isLiveActivityActive(activityName: string): boolean
+  isHeadless(): boolean
+  preloadImages(images: PreloadImageOptions[]): Promise<PreloadImagesResult>
+  reloadLiveActivities(activityNames?: string[] | null): Promise<void>
+  clearPreloadedImages(keys?: string[] | null): 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[]>
+  setWidgetServerCredentials(credentials: WidgetServerCredentials): Promise<void>
+  clearWidgetServerCredentials(): Promise<void>
+}
+
+export function getNativeVoltra(): Spec {
+  const voltraModule = TurboModuleRegistry.get<Spec>('NativeVoltra')
+
+  if (voltraModule == null) {
+    throw new Error('NativeVoltra is not available')
+  }
+
+  return voltraModule
+}

package/src/native/VoltraRNNativeComponent.ts

@@ -0,0 +1,9 @@
+import type { HostComponent, ViewProps } from 'react-native'
+import { codegenNativeComponent } from 'react-native'
+
+export interface NativeProps extends ViewProps {
+  payload: string
+  viewId: string
+}
+
+export default codegenNativeComponent<NativeProps>('VoltraView') as HostComponent<NativeProps>

package/src/preload.ts

@@ -0,0 +1,50 @@
+import { Platform } from 'react-native'
+
+import type { PreloadImageOptions, PreloadImagesResult } from './types.js'
+import { getNativeVoltra } from './VoltraModule.js'
+
+export type { PreloadImageOptions, PreloadImagesResult } from './types.js'
+
+function assertIOS(name: string): boolean {
+  const isIOS = Platform.OS === 'ios'
+  if (!isIOS) console.error(`${name} is only available on iOS`)
+  return isIOS
+}
+
+export async function preloadImages(images: PreloadImageOptions[]): Promise<PreloadImagesResult> {
+  if (!assertIOS('preloadImages')) {
+    return { succeeded: [], failed: images.map((img) => ({ key: img.key, error: 'Not available on this platform' })) }
+  }
+
+  try {
+    return await getNativeVoltra().preloadImages(images)
+  } catch (error) {
+    return {
+      succeeded: [],
+      failed: images.map((img) => ({
+        key: img.key,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      })),
+    }
+  }
+}
+
+export async function reloadLiveActivities(activityNames?: string[]): Promise<void> {
+  if (!assertIOS('reloadLiveActivities')) return
+
+  try {
+    await getNativeVoltra().reloadLiveActivities(activityNames ?? null)
+  } catch (error) {
+    console.error('Failed to reload Live Activities:', error)
+  }
+}
+
+export async function clearPreloadedImages(keys?: string[]): Promise<void> {
+  if (!assertIOS('clearPreloadedImages')) return
+
+  try {
+    await getNativeVoltra().clearPreloadedImages(keys ?? null)
+  } catch (error) {
+    console.error('Failed to clear preloaded images:', error)
+  }
+}

package/src/types.ts

@@ -0,0 +1,12 @@
+export type {
+  EventSubscription,
+  PreloadImageFailure,
+  PreloadImageOptions,
+  PreloadImagesResult,
+  UpdateWidgetOptions,
+  VoltraElementJson,
+  VoltraElementRef,
+  VoltraNodeJson,
+  VoltraPropValue,
+  WidgetServerCredentials,
+} from '@use-voltra/ios'

package/src/utils/assertRunningOnApple.ts

@@ -0,0 +1,10 @@
+import { Platform } from 'react-native'
+
+export const assertRunningOnApple = (): boolean => {
+  if (Platform.OS !== 'ios') {
+    console.error(`Voltra is available only on iOS!`)
+    return false
+  }
+
+  return true
+}

package/src/utils/helpers.ts

@@ -0,0 +1 @@
+export { isGlassSupported, isHeadless } from '../helpers.js'

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './assertRunningOnApple.js'
+export * from './useUpdateOnHMR.js'

package/src/utils/useUpdateOnHMR.ts

@@ -0,0 +1,25 @@
+import { useEffect, useState } from 'react'
+
+declare global {
+  var __accept: (...args: unknown[]) => void
+}
+
+export const useUpdateOnHMR = () => {
+  const [, forceUpdate] = useState(0)
+
+  useEffect(() => {
+    if (!__DEV__) {
+      return
+    }
+
+    const oldAccept = global['__accept']
+    global['__accept'] = (...args) => {
+      forceUpdate((prev) => prev + 1)
+      oldAccept?.(...args)
+    }
+
+    return () => {
+      global['__accept'] = oldAccept
+    }
+  }, [])
+}

package/src/widgets/server-credentials.ts

@@ -0,0 +1,16 @@
+import type { WidgetServerCredentials } from '../types.js'
+import { getNativeVoltra } from '../VoltraModule.js'
+
+export type { WidgetServerCredentials } from '../types.js'
+
+export async function setWidgetServerCredentials(credentials: WidgetServerCredentials): Promise<void> {
+  if (!credentials.token) {
+    throw new Error('[Voltra][iOS] setWidgetServerCredentials: token is required')
+  }
+
+  return getNativeVoltra().setWidgetServerCredentials(credentials)
+}
+
+export async function clearWidgetServerCredentials(): Promise<void> {
+  return getNativeVoltra().clearWidgetServerCredentials()
+}

package/src/widgets/widget-api.ts

@@ -0,0 +1,65 @@
+import { renderWidgetToString, type ScheduledWidgetEntry, type WidgetInfo, type WidgetVariants } from '@use-voltra/ios'
+
+import type { UpdateWidgetOptions } from '../types.js'
+import { assertRunningOnApple } from '../utils/assertRunningOnApple.js'
+import { getNativeVoltra } from '../VoltraModule.js'
+
+export type { UpdateWidgetOptions } from '../types.js'
+export type { ScheduledWidgetEntry, WidgetInfo } from '@use-voltra/ios'
+
+export const updateWidget = async (
+  widgetId: string,
+  variants: WidgetVariants,
+  options?: UpdateWidgetOptions
+): Promise<void> => {
+  if (!assertRunningOnApple()) return Promise.resolve()
+
+  const payload = renderWidgetToString(variants)
+
+  return getNativeVoltra().updateWidget(widgetId, payload, {
+    deepLinkUrl: options?.deepLinkUrl,
+  })
+}
+
+export const reloadWidgets = async (widgetIds?: string[]): Promise<void> => {
+  if (!assertRunningOnApple()) return Promise.resolve()
+
+  return getNativeVoltra().reloadWidgets(widgetIds ?? null)
+}
+
+export const clearWidget = async (widgetId: string): Promise<void> => {
+  if (!assertRunningOnApple()) return Promise.resolve()
+
+  return getNativeVoltra().clearWidget(widgetId)
+}
+
+export const clearAllWidgets = async (): Promise<void> => {
+  if (!assertRunningOnApple()) return Promise.resolve()
+
+  return getNativeVoltra().clearAllWidgets()
+}
+
+export const scheduleWidget = async (widgetId: string, entries: ScheduledWidgetEntry[]): Promise<void> => {
+  if (!assertRunningOnApple()) return Promise.resolve()
+
+  const renderedEntries = entries.map((entry) => ({
+    date: entry.date.getTime(),
+    json: renderWidgetToString(entry.variants),
+    deepLinkUrl: entry.deepLinkUrl,
+  }))
+
+  const timelineData = {
+    entries: renderedEntries,
+    policy: { type: 'never' },
+  }
+
+  const timelineJson = JSON.stringify(timelineData)
+
+  return getNativeVoltra().scheduleWidget(widgetId, timelineJson)
+}
+
+export const getActiveWidgets = async (): Promise<WidgetInfo[]> => {
+  if (!assertRunningOnApple()) return []
+
+  return getNativeVoltra().getActiveWidgets()
+}

package/ios/ui/Generated/Parameters/.generated

@@ -1,8 +0,0 @@
-This directory contains auto-generated Swift parameter files.
-DO NOT EDIT MANUALLY.
-
-Generated from: data/components.json
-Schema version: 1.0.0
-
-To regenerate these files, run:
-  npm run generate