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

package/expo-plugin/src/ios/eas.ts

@@ -0,0 +1,33 @@
+import { ConfigPlugin } from '@expo/config-plugins'
+
+import { addApplicationGroupsEntitlement } from '@use-voltra/expo-plugin'
+
+export interface ConfigureEasProps {
+  groupIdentifier?: string
+}
+
+/**
+ * Configures main app for EAS builds.
+ *
+ * This adds the app group entitlement to the main app's entitlements
+ * so that EAS can properly configure provisioning profiles.
+ */
+export const configureEas: ConfigPlugin<ConfigureEasProps> = (config, props = {}) => {
+  if (!props.groupIdentifier) {
+    // No group identifier provided, skip EAS configuration
+    return config
+  }
+
+  // Ensure ios.entitlements exists in config for EAS to detect
+  if (!config.ios) {
+    config.ios = {}
+  }
+  if (!config.ios.entitlements) {
+    config.ios.entitlements = {}
+  }
+
+  // Add app groups entitlement for EAS
+  addApplicationGroupsEntitlement(config.ios.entitlements, props.groupIdentifier)
+
+  return config
+}

package/expo-plugin/src/ios/entitlements.ts

@@ -0,0 +1,59 @@
+import { ConfigPlugin } from '@expo/config-plugins'
+
+import { addApplicationGroupsEntitlement } from '@use-voltra/expo-plugin'
+
+export interface ConfigureEntitlementsProps {
+  groupIdentifier?: string
+  keychainGroup?: string
+}
+
+/**
+ * Configures main app entitlements for app groups and keychain sharing.
+ *
+ * This adds:
+ * - com.apple.security.application-groups entitlement for data sharing
+ * - keychain-access-groups entitlement for shared credential access (if keychainGroup provided)
+ */
+export const configureEntitlements: ConfigPlugin<ConfigureEntitlementsProps> = (config, props = {}) => {
+  if (!props.groupIdentifier && !props.keychainGroup) {
+    // Nothing to configure
+    return config
+  }
+
+  if (!config.ios) {
+    config.ios = {}
+  }
+  if (!config.ios.entitlements) {
+    config.ios.entitlements = {}
+  }
+
+  if (props.groupIdentifier) {
+    addApplicationGroupsEntitlement(config.ios.entitlements, props.groupIdentifier)
+  }
+
+  if (props.keychainGroup) {
+    addKeychainAccessGroupEntitlement(config.ios.entitlements, props.keychainGroup)
+  }
+
+  return config
+}
+
+/**
+ * Adds keychain-access-groups entitlement to an entitlements object.
+ * Ensures the group list is deduped and preserves existing order.
+ */
+function addKeychainAccessGroupEntitlement(
+  entitlements: Record<string, any>,
+  keychainGroup: string
+): Record<string, any> {
+  const existingGroups = ((entitlements['keychain-access-groups'] as string[]) ?? []).filter(Boolean)
+  const deduped = Array.from(new Set(existingGroups))
+
+  if (deduped.includes(keychainGroup)) {
+    entitlements['keychain-access-groups'] = deduped
+    return entitlements
+  }
+
+  entitlements['keychain-access-groups'] = [...deduped, keychainGroup]
+  return entitlements
+}

package/expo-plugin/src/ios/index.ts

@@ -0,0 +1,47 @@
+import type { ExpoConfig } from 'expo/config'
+
+import { configureEas } from './eas'
+import { configureEntitlements } from './entitlements'
+import { configureInfoPlist } from './infoPlist'
+
+export interface IOSConfigProps {
+  groupIdentifier?: string
+  widgetIds?: string[]
+  widgets?: import('../types').IOSWidgetConfig[]
+  keychainGroup?: string
+}
+
+/**
+ * Main iOS app configuration.
+ *
+ * This configures the main app (not the widget extension) for:
+ * - Live Activities support (Info.plist)
+ * - App groups for widget communication (entitlements)
+ * - Keychain sharing for widget server credentials (entitlements)
+ * - EAS build configuration
+ */
+export function withIOS(config: ExpoConfig, props: IOSConfigProps): ExpoConfig {
+  // Configure Info.plist
+  config = configureInfoPlist(config, {
+    groupIdentifier: props.groupIdentifier,
+    widgetIds: props.widgetIds,
+    widgets: props.widgets,
+    keychainGroup: props.keychainGroup,
+  })
+
+  // Configure entitlements
+  config = configureEntitlements(config, {
+    groupIdentifier: props.groupIdentifier,
+    keychainGroup: props.keychainGroup,
+  })
+
+  // Configure EAS
+  config = configureEas(config, {
+    groupIdentifier: props.groupIdentifier,
+  })
+
+  return config
+}
+
+// Re-export for convenience
+export { withPushNotifications } from './pushNotifications'

package/expo-plugin/src/ios/infoPlist.ts

@@ -0,0 +1,63 @@
+import { ConfigPlugin, withInfoPlist } from '@expo/config-plugins'
+
+import type { IOSWidgetConfig } from '../types'
+
+export interface ConfigureInfoPlistProps {
+  groupIdentifier?: string
+  widgetIds?: string[]
+  widgets?: IOSWidgetConfig[]
+  keychainGroup?: string
+}
+
+/**
+ * Configures main app Info.plist for Live Activities and widgets.
+ *
+ * This adds:
+ * - NSSupportsLiveActivities: Enables Live Activities support
+ * - Voltra_AppGroupIdentifier: App group ID for widget communication (if provided)
+ * - Voltra_WidgetIds: Array of widget IDs for native module access (if provided)
+ * - Voltra_WidgetServerUrls: Map of widget IDs to server URLs (if any widgets have serverUpdate)
+ * - Voltra_WidgetServerIntervals: Map of widget IDs to update intervals (if any widgets have serverUpdate)
+ * - Voltra_KeychainGroup: Keychain access group for shared credentials (if provided)
+ */
+export const configureInfoPlist: ConfigPlugin<ConfigureInfoPlistProps> = (config, props = {}) => {
+  return withInfoPlist(config, (mod) => {
+    mod.modResults.NSSupportsLiveActivities = true
+    mod.modResults.NSSupportsLiveActivitiesFrequentUpdates = false
+
+    // Only add group identifier if provided
+    if (props.groupIdentifier) {
+      mod.modResults.Voltra_AppGroupIdentifier = props.groupIdentifier
+    }
+
+    // Store widget IDs in Info.plist for native module to access
+    if (props.widgetIds && props.widgetIds.length > 0) {
+      mod.modResults.Voltra_WidgetIds = props.widgetIds
+    }
+
+    // Configure server update URLs and intervals for widgets
+    if (props.widgets && props.widgets.length > 0) {
+      const serverUrls: Record<string, string> = {}
+      const serverIntervals: Record<string, number> = {}
+
+      for (const widget of props.widgets) {
+        if (widget.serverUpdate) {
+          serverUrls[widget.id] = widget.serverUpdate.url
+          serverIntervals[widget.id] = widget.serverUpdate.intervalMinutes ?? 15
+        }
+      }
+
+      if (Object.keys(serverUrls).length > 0) {
+        mod.modResults.Voltra_WidgetServerUrls = serverUrls
+        mod.modResults.Voltra_WidgetServerIntervals = serverIntervals
+      }
+    }
+
+    // Store Keychain group identifier for shared credential access
+    if (props.keychainGroup) {
+      mod.modResults.Voltra_KeychainGroup = props.keychainGroup
+    }
+
+    return mod
+  })
+}

package/expo-plugin/src/ios/pushNotifications.ts

@@ -0,0 +1,22 @@
+import { ConfigPlugin, withEntitlementsPlist, withInfoPlist } from '@expo/config-plugins'
+
+/**
+ * Plugin that enables push notification support for Live Activities.
+ *
+ * This:
+ * - Adds the aps-environment entitlement for push notifications
+ * - Adds Voltra_EnablePushNotifications flag to Info.plist
+ */
+export const withPushNotifications: ConfigPlugin = (config) =>
+  withInfoPlist(
+    withEntitlementsPlist(config, (mod) => {
+      // NOTE: For App Store builds, provisioning profiles typically inject 'production'.
+      // This sets a default for debug/dev builds.
+      mod.modResults['aps-environment'] = 'development'
+      return mod
+    }),
+    (mod) => {
+      mod.modResults['Voltra_EnablePushNotifications'] = true
+      return mod
+    }
+  )

package/expo-plugin/src/ios-widget/eas.ts

@@ -0,0 +1,79 @@
+import { ConfigPlugin } from '@expo/config-plugins'
+
+import { addApplicationGroupsEntitlement } from '@use-voltra/expo-plugin'
+import { getWidgetExtensionEntitlements } from './files/entitlements'
+
+export interface ConfigureEasBuildProps {
+  bundleIdentifier: string
+  targetName: string
+  groupIdentifier?: string
+}
+
+/**
+ * Plugin step that configures EAS build settings for the widget extension.
+ *
+ * This:
+ * - Adds the widget extension to the EAS build experimental iOS appExtensions
+ * - Configures entitlements for both the extension and main app
+ */
+export const configureEasBuild: ConfigPlugin<ConfigureEasBuildProps> = (
+  config,
+  { bundleIdentifier, targetName, groupIdentifier }
+) => {
+  let configIndex: null | number = null
+
+  // Check if extension already exists
+  config.extra?.eas?.build?.experimental?.ios?.appExtensions?.forEach((ext: any, index: number) => {
+    if (ext.targetName === targetName) {
+      configIndex = index
+    }
+  })
+
+  // Add extension if not already present
+  if (configIndex === null) {
+    config.extra = {
+      ...config.extra,
+      eas: {
+        ...config.extra?.eas,
+        build: {
+          ...config.extra?.eas?.build,
+          experimental: {
+            ...config.extra?.eas?.build?.experimental,
+            ios: {
+              ...config.extra?.eas?.build?.experimental?.ios,
+              appExtensions: [
+                ...(config.extra?.eas?.build?.experimental?.ios?.appExtensions ?? []),
+                {
+                  targetName,
+                  bundleIdentifier,
+                },
+              ],
+            },
+          },
+        },
+      },
+    }
+    configIndex = (config.extra?.eas?.build?.experimental?.ios?.appExtensions?.length ?? 1) - 1
+  }
+
+  // Configure entitlements (may be empty if no groupIdentifier)
+  if (configIndex != null && config.extra) {
+    const widgetsExtensionConfig = config.extra.eas.build.experimental.ios.appExtensions[configIndex]
+
+    widgetsExtensionConfig.entitlements = {
+      ...widgetsExtensionConfig.entitlements,
+      ...getWidgetExtensionEntitlements(groupIdentifier),
+    }
+
+    if (groupIdentifier) {
+      config.ios = {
+        ...config.ios,
+        entitlements: {
+          ...addApplicationGroupsEntitlement(config.ios?.entitlements ?? {}, groupIdentifier),
+        },
+      }
+    }
+  }
+
+  return config
+}

package/expo-plugin/src/ios-widget/files/assets.ts

@@ -0,0 +1,201 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { MAX_IMAGE_SIZE_BYTES, logger } from '@use-voltra/expo-plugin'
+
+import { DEFAULT_USER_IMAGES_PATH, SUPPORTED_IMAGE_EXTENSIONS } from '../../constants'
+
+export interface GenerateAssetsOptions {
+  targetPath: string
+  userImagesPath?: string
+}
+
+// ============================================================================
+// Main Function
+// ============================================================================
+
+/**
+ * Generates all asset files for the widget extension.
+ *
+ * This creates:
+ * - Assets.xcassets/ directory structure
+ * - Copies user images to the asset catalog
+ */
+export function generateAssets(options: GenerateAssetsOptions): void {
+  const { targetPath, userImagesPath = DEFAULT_USER_IMAGES_PATH } = options
+
+  // Generate Assets.xcassets structure
+  generateAssetsCatalog(targetPath)
+  logger.info('Generated Assets.xcassets')
+
+  // Copy user images to asset catalog
+  const assetsPath = path.join(targetPath, 'Assets.xcassets')
+  copyUserImages(userImagesPath, assetsPath)
+}
+
+// ============================================================================
+// Asset Catalog
+// ============================================================================
+
+/**
+ * Contents.json for the root of Assets.xcassets
+ */
+const ASSETS_CATALOG_CONTENTS = {
+  info: {
+    author: 'xcode',
+    version: 1,
+  },
+}
+
+/**
+ * Contents.json for an imageset
+ */
+function createImagesetContents(filename: string) {
+  return {
+    images: [
+      {
+        filename,
+        idiom: 'universal',
+      },
+    ],
+    info: {
+      author: 'xcode',
+      version: 1,
+    },
+  }
+}
+
+/**
+ * Generates the Assets.xcassets directory structure for a widget extension.
+ *
+ * Creates the minimal required asset catalog structure:
+ * - Assets.xcassets/
+ *   - Contents.json (required root manifest)
+ *
+ * @param targetPath - Path to the widget extension target directory
+ */
+function generateAssetsCatalog(targetPath: string): void {
+  const assetsPath = path.join(targetPath, 'Assets.xcassets')
+
+  // Create Assets.xcassets directory
+  if (!fs.existsSync(assetsPath)) {
+    fs.mkdirSync(assetsPath, { recursive: true })
+  }
+
+  // Write root Contents.json
+  fs.writeFileSync(path.join(assetsPath, 'Contents.json'), JSON.stringify(ASSETS_CATALOG_CONTENTS, null, 2))
+}
+
+/**
+ * Adds an image to the Assets.xcassets catalog as an imageset.
+ *
+ * Creates:
+ * - {imageName}.imageset/
+ *   - {originalFilename}
+ *   - Contents.json
+ *
+ * @param assetsPath - Path to Assets.xcassets directory
+ * @param imagePath - Path to the source image file
+ */
+function addImageToAssetsCatalog(assetsPath: string, imagePath: string): void {
+  const filename = path.basename(imagePath)
+  const imageName = path.basename(filename, path.extname(filename))
+  const imagesetPath = path.join(assetsPath, `${imageName}.imageset`)
+
+  // Create imageset directory
+  if (!fs.existsSync(imagesetPath)) {
+    fs.mkdirSync(imagesetPath, { recursive: true })
+  }
+
+  // Copy the image file
+  fs.copyFileSync(imagePath, path.join(imagesetPath, filename))
+
+  // Write Contents.json for the imageset
+  fs.writeFileSync(path.join(imagesetPath, 'Contents.json'), JSON.stringify(createImagesetContents(filename), null, 2))
+}
+
+// ============================================================================
+// Image Handling
+// ============================================================================
+
+/**
+ * Checks if an image file exceeds the size limit for Live Activities.
+ * Logs a warning if the image is too large.
+ *
+ * @param imagePath - Path to the image file
+ * @returns true if the image is within the size limit, false otherwise
+ */
+function checkImageSize(imagePath: string): boolean {
+  const stats = fs.statSync(imagePath)
+  const imageSizeInBytes = stats.size
+
+  if (imageSizeInBytes >= MAX_IMAGE_SIZE_BYTES) {
+    const fileName = path.basename(imagePath)
+    logger.warnRed(
+      `Image "${fileName}" is ${imageSizeInBytes} bytes (${(imageSizeInBytes / 1024).toFixed(2)}KB). ` +
+        `This image will not display correctly in Live Activities as images for Live Activities need to be lower than 4KB.`
+    )
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Checks if a file is a supported image type.
+ */
+function isSupportedImage(filePath: string): boolean {
+  return SUPPORTED_IMAGE_EXTENSIONS.test(path.extname(filePath))
+}
+
+/**
+ * Copies user images from the source directory to the widget's Assets.xcassets.
+ *
+ * Images are validated for size (must be < 4KB for Live Activities) and
+ * added as imagesets to the asset catalog.
+ *
+ * @param userImagesPath - Path to directory containing user images (relative to project root)
+ * @param targetAssetsPath - Path to the Assets.xcassets directory in the widget target
+ * @returns Array of image filenames that were copied
+ */
+function copyUserImages(userImagesPath: string, targetAssetsPath: string): string[] {
+  const copiedImages: string[] = []
+
+  if (!fs.existsSync(userImagesPath)) {
+    logger.warn(`Skipping user images: directory does not exist at ${userImagesPath}`)
+    return copiedImages
+  }
+
+  if (!fs.lstatSync(userImagesPath).isDirectory()) {
+    logger.warn(`Skipping user images: ${userImagesPath} is not a directory`)
+    return copiedImages
+  }
+
+  const files = fs.readdirSync(userImagesPath)
+
+  for (const file of files) {
+    const sourcePath = path.join(userImagesPath, file)
+
+    // Skip directories and non-image files
+    if (fs.lstatSync(sourcePath).isDirectory()) {
+      continue
+    }
+
+    if (!isSupportedImage(file)) {
+      continue
+    }
+
+    // Check image size for Live Activity compatibility (warns if too large)
+    checkImageSize(sourcePath)
+
+    // Add to asset catalog
+    addImageToAssetsCatalog(targetAssetsPath, sourcePath)
+    copiedImages.push(file)
+  }
+
+  if (copiedImages.length > 0) {
+    logger.info(`Copied ${copiedImages.length} user image(s) to widget assets`)
+  }
+
+  return copiedImages
+}

package/expo-plugin/src/ios-widget/files/entitlements.ts

@@ -0,0 +1,48 @@
+import plist from '@expo/plist'
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { addApplicationGroupsEntitlement } from '@use-voltra/expo-plugin'
+import { logger } from '@use-voltra/expo-plugin'
+
+/**
+ * Gets the entitlements for the widget extension.
+ */
+export function getWidgetExtensionEntitlements(groupIdentifier?: string, keychainGroup?: string): Record<string, any> {
+  const entitlements: Record<string, any> = {}
+  if (groupIdentifier) {
+    addApplicationGroupsEntitlement(entitlements, groupIdentifier)
+  }
+  if (keychainGroup) {
+    const existingGroups = ((entitlements['keychain-access-groups'] as string[]) ?? []).filter(Boolean)
+    const deduped = Array.from(new Set(existingGroups))
+    if (!deduped.includes(keychainGroup)) {
+      deduped.push(keychainGroup)
+    }
+    entitlements['keychain-access-groups'] = deduped
+  }
+  return entitlements
+}
+
+export interface GenerateEntitlementsOptions {
+  targetPath: string
+  targetName: string
+  groupIdentifier?: string
+  keychainGroup?: string
+}
+
+/**
+ * Generates the entitlements file for the widget extension.
+ *
+ * @param options - Generation options
+ */
+export function generateEntitlements(options: GenerateEntitlementsOptions): void {
+  const { targetPath, targetName, groupIdentifier, keychainGroup } = options
+  const filePath = path.join(targetPath, `${targetName}.entitlements`)
+
+  const extensionEntitlements = getWidgetExtensionEntitlements(groupIdentifier, keychainGroup)
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, plist.build(extensionEntitlements))
+  logger.info(`Generated ${targetName}.entitlements`)
+}

package/expo-plugin/src/ios-widget/files/index.ts

@@ -0,0 +1,74 @@
+import { ConfigPlugin, withDangerousMod } from '@expo/config-plugins'
+import * as fs from 'fs'
+import * as path from 'path'
+
+import type { IOSWidgetConfig } from '../../types'
+import { generateAssets } from './assets'
+import { generateEntitlements } from './entitlements'
+import { generateInfoPlist } from './infoPlist'
+import { generateSwiftFiles } from './swift'
+
+export interface GenerateWidgetExtensionFilesProps {
+  targetName: string
+  widgets?: IOSWidgetConfig[]
+  groupIdentifier?: string
+  keychainGroup?: string
+  version: string
+  buildNumber: string
+}
+
+/**
+ * Plugin step that generates all widget extension files.
+ *
+ * This creates:
+ * - Info.plist (required extension manifest)
+ * - Assets.xcassets/ (asset catalog with user images)
+ * - VoltraWidgetBundle.swift (widget bundle definition)
+ * - VoltraWidgetInitialStates.swift (pre-rendered widget states)
+ * - {targetName}.entitlements (entitlements file)
+ *
+ * This should run before configureXcodeProject so the files exist when Xcode project is configured.
+ */
+export const generateWidgetExtensionFiles: ConfigPlugin<GenerateWidgetExtensionFilesProps> = (config, props) => {
+  const { targetName, widgets, groupIdentifier, keychainGroup, version, buildNumber } = props
+
+  return withDangerousMod(config, [
+    'ios',
+    async (config) => {
+      if (config.modRequest.introspect) {
+        return config
+      }
+
+      const { platformProjectRoot, projectRoot } = config.modRequest
+      const targetPath = path.join(platformProjectRoot, targetName)
+
+      // Ensure target directory exists
+      if (!fs.existsSync(targetPath)) {
+        fs.mkdirSync(targetPath, { recursive: true })
+      }
+
+      // Generate Info.plist
+      generateInfoPlist(targetPath, targetName, version, buildNumber)
+
+      // Generate Assets.xcassets and copy user images
+      generateAssets({ targetPath })
+
+      // Generate Swift files (widget bundle, initial states)
+      await generateSwiftFiles({
+        targetPath,
+        projectRoot,
+        widgets,
+      })
+
+      // Generate entitlements file (may be empty if no groupIdentifier or keychainGroup)
+      generateEntitlements({
+        targetPath,
+        targetName,
+        groupIdentifier,
+        keychainGroup,
+      })
+
+      return config
+    },
+  ])
+}

package/expo-plugin/src/ios-widget/files/infoPlist.ts

@@ -0,0 +1,57 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { logger } from '@use-voltra/expo-plugin'
+
+/**
+ * Generates the Info.plist content for a WidgetKit extension.
+ *
+ * This includes version information and the required WidgetKit extension point.
+ * Version keys are written directly to the plist following the Expo pattern.
+ */
+function generateInfoPlistContent(targetName: string, version: string, buildNumber: string): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>${targetName}</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>$(PRODUCT_BUNDLE_PACKAGE_TYPE)</string>
+	<key>CFBundleShortVersionString</key>
+	<string>${version}</string>
+	<key>CFBundleVersion</key>
+	<string>${buildNumber}</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.widgetkit-extension</string>
+	</dict>
+</dict>
+</plist>
+`
+}
+
+/**
+ * Generates the Info.plist file for the widget extension.
+ *
+ * @param targetPath - Path to the widget extension target directory
+ * @param targetName - The widget extension target name (used for CFBundleDisplayName)
+ * @param version - The app version (CFBundleShortVersionString)
+ * @param buildNumber - The build number (CFBundleVersion)
+ */
+export function generateInfoPlist(targetPath: string, targetName: string, version: string, buildNumber: string): void {
+  const infoPlistPath = path.join(targetPath, 'Info.plist')
+  fs.writeFileSync(infoPlistPath, generateInfoPlistContent(targetName, version, buildNumber))
+  logger.info('Generated Info.plist')
+}