@unif/react-native-hms-scan 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unif-design
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @unif/react-native-hms-scan
+
+华为 **HMS 统一扫码服务**（HUAWEI Scan Kit）的 React Native 封装，新架构（TurboModule + Fabric）。聚焦两件事：
+
+- **定制视图扫码** —— 底层 headless `<HmsScanView>` 相机组件，外加按设计稿做好的成品 `<Scanner>` 扫一扫页（聚焦款，浅色）。
+- **图片识别** —— `decodeImage(uri)` 从本地图片解码条码 / 二维码。
+
+> Android 用 **Scan SDK-Plus**（内置引擎，**不依赖设备安装 HMS Core APK**，非华为机型可用）；iOS 用 CocoaPods 的 **ScanKitFrameWork**。两端**都不需要 AppGallery Connect / agconnect 配置 / API Key**。
+
+## 安装
+
+```sh
+yarn add @unif/react-native-hms-scan react-native-svg
+cd ios && pod install
+```
+
+`react-native-svg` 是 peer 依赖（`<Scanner>` 的图标用它绘制）。本库为 New Architecture 库，宿主需开启新架构。
+
+### Android
+
+库的 gradle 已自带华为 maven 仓库与 `com.huawei.hms:scanplus` 依赖，**无需改宿主 gradle**。只需在宿主 `AndroidManifest.xml` 声明权限：
+
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-feature android:name="android.hardware.camera" android:required="false" />
+<!-- 仅当用 decodeImage 解相册图时需要 -->
+<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />          <!-- API 33+ -->
+<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
+    android:maxSdkVersion="32" />
+```
+
+- minSdkVersion ≥ 24。
+- **不需要** `agconnect-services.json` / agconnect 插件 / API Key。
+
+### iOS
+
+`pod install` 会自动拉取 `ScanKitFrameWork`。在宿主 `Info.plist` 加：
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>用于扫描商品条码与门店二维码</string>
+<!-- 仅当用 decodeImage 解相册图时需要 -->
+<key>NSPhotoLibraryUsageDescription</key>
+<string>用于从相册选取图片识别条码</string>
+```
+
+- 最低 iOS 版本随宿主 RN 工程。
+- `ScanKitFrameWork` 是 **arm64-only 静态库**：podspec 已对 Apple 芯片模拟器排掉 arm64（模拟器走 x86_64），**真机 arm64 不受影响**；建议在真机调试扫码。
+- **不需要** AppGallery Connect / API Key。
+
+## 用法
+
+### 1) 成品扫一扫页 `<Scanner>`（推荐）
+
+```tsx
+import { Scanner, type ScanResult, type ScanProduct } from '@unif/react-native-hms-scan';
+
+function ScanScreen({ navigation }) {
+  return (
+    <Scanner
+      title="扫一扫"
+      onClose={() => navigation.goBack()}
+      // 扫到条码后解析商品（你的业务：查接口/本地库）。返回 null = 未识别。
+      resolveProduct={async (r: ScanResult): Promise<ScanProduct | null> => {
+        const p = await api.lookupByBarcode(r.value);
+        return p && {
+          name: p.name, brand: p.brand, price: `¥${p.price}`,
+          spec: p.spec, stockShort: p.stockText, barcode: r.value,
+        };
+      }}
+      // 点"确认"：把结果带回上一级
+      onConfirm={(product, result) => {
+        navigation.navigate('Order', { barcode: result.value, product });
+      }}
+      // 点"相册"：用你自己的图片选择器返回本地 uri
+      pickImage={async () => {
+        const res = await launchImageLibrary({ mediaType: 'photo' });
+        return res.assets?.[0]?.uri ?? null;
+      }}
+    />
+  );
+}
+```
+
+`<Scanner>` 内部状态：取景 → 识别中 → 识别成功（浮层确认卡）/ 未识别（重试弹层）/ 无权限（去设置）。单次扫一个，确认后带回上一级。手电筒 / 相册在底部工具栏。
+
+> 安全区：默认 `topInset=54 / bottomInset=34`。若用 `react-native-safe-area-context`，把 `insets.top/bottom` 传进来更精准。
+
+### 2) 底层 headless 组件 `<HmsScanView>`
+
+完全自定义 UI 时，只用相机预览 + 结果事件，自己画取景框：
+
+```tsx
+import { HmsScanView, type ScanResult } from '@unif/react-native-hms-scan';
+
+<HmsScanView
+  style={{ flex: 1 }}
+  formats={['QR_CODE', 'EAN_13']}   // 不传 = 全部码制
+  torch={torchOn}                   // Android 可控；iOS 为尽力而为
+  paused={paused}                   // 命中后想停在结果时置 true
+  onScanResult={(results: ScanResult[]) => {
+    const code = results[0]?.value;
+  }}
+  onScanError={(e) => console.warn(e.code, e.message)}
+/>
+```
+
+### 3) 图片识别 `decodeImage`
+
+```tsx
+import { decodeImage } from '@unif/react-native-hms-scan';
+
+const results = await decodeImage('file:///path/photo.jpg', { formats: ['QR_CODE'] });
+// results: ScanResult[]（可能为空）。只吃本地 uri，远程图请先下载。
+```
+
+### 4) 相机权限
+
+```tsx
+import { getCameraPermissionStatus, requestCameraPermission } from '@unif/react-native-hms-scan';
+const status = await requestCameraPermission(); // 'granted' | 'denied' | 'blocked' | 'undetermined'
+```
+
+## 平台差异（务必知悉）
+
+| 能力 | Android (`RemoteView`) | iOS (`HmsCustomScanViewController`) |
+| --- | --- | --- |
+| 手电筒 `torch` | ✅ 可编程控制 | ⚠️ HMS 无公开手电 API；本库走 `AVCaptureDevice` **尽力而为**，不保证 |
+| 变焦 | ❌ 仅内部自动 | ❌ 仅内部自动 |
+| 暗光提示 `onTorchStatus.available` | ✅ 上报 | ❌ 不上报 |
+
+## 测试（Jest）
+
+消费者在测试里可用内置 mock 替换本库（避免加载原生）：
+
+```ts
+jest.mock('@unif/react-native-hms-scan', () =>
+  require('@unif/react-native-hms-scan/mock')
+);
+// decodeImage / 权限方法是 jest.fn；<HmsScanView>/<Scanner> 渲染为 null。
+```
+
+## 类型一览
+
+`BarcodeFormat`（QR_CODE / EAN_13 / … / UNKNOWN）、`BarcodeContentType`、`ScanResult { value, format, contentType?, cornerPoints? }`、`ScanProduct`、`CameraPermissionStatus`、`HmsScanError`。
+
+## 许可
+
+MIT © unif-design

package/ReactNativeHmsScan.podspec

@@ -0,0 +1,30 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ReactNativeHmsScan"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/unif-design/react-native-hms-scan.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  # 华为 HUAWEI Scan Kit（iOS 自包含，无需 AppGallery Connect / API Key）。
+  # 提供 HmsCustomScanViewController（定制视图）与 HmsBitMap（图片识别）。
+  s.dependency "ScanKitFrameWork", "~> 1.1.2"
+
+  # ScanKitFrameWork 是 arm64-only 的静态 framework，不含模拟器 arm64 切片。
+  # 在 Apple 芯片上排掉模拟器 arm64（模拟器走 x86_64 / Rosetta），真机 arm64 不受影响。
+  s.pod_target_xcconfig  = { "EXCLUDED_ARCHS[sdk=iphonesimulator*]" => "arm64" }
+  s.user_target_xcconfig = { "EXCLUDED_ARCHS[sdk=iphonesimulator*]" => "arm64" }
+
+  # 接入 New Architecture（Fabric 组件 + TurboModule）的 codegen 依赖。
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,79 @@
+buildscript {
+  ext.ReactNativeHmsScan = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return ReactNativeHmsScan[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+// "com.facebook.react" triggers RN codegen for this library (TurboModule spec +
+// Fabric view manager interface/delegate) when the host app builds.
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.unif.reactnativehmsscan"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+    // Ship Huawei HMS keep rules to the consuming app so release builds don't strip them.
+    consumerProguardFiles 'consumer-rules.pro'
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+  // Huawei Maven repository hosting the HMS Scan Kit (Scan SDK-Plus) artifacts.
+  maven { url 'https://developer.huawei.com/repo/' }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  // HUAWEI Scan Kit, Scan SDK-Plus (RemoteView + ScanUtil.decodeWithBitmap).
+  // No AppGallery Connect / agconnect plugin / API key required for these APIs.
+  implementation 'com.huawei.hms:scanplus:2.15.0.301'
+}

package/android/consumer-rules.pro

@@ -0,0 +1,13 @@
+# Keep rules for HUAWEI Scan Kit (Scan SDK-Plus). Shipped to the consuming app via
+# consumerProguardFiles so release (minified) builds keep the HMS reflection targets.
+# Mirrors the official hms-scan-demo proguard configuration.
+-ignorewarnings
+-keepattributes *Annotation*
+-keepattributes Exceptions
+-keepattributes InnerClasses
+-keepattributes Signature
+-keepattributes SourceFile,LineNumberTable
+
+-keep class com.huawei.hianalytics.**{*;}
+-keep class com.huawei.updatesdk.**{*;}
+-keep class com.huawei.hms.**{*;}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,23 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <!-- Camera preview / scanning (RemoteView). -->
+  <uses-permission android:name="android.permission.CAMERA" />
+
+  <!-- Reading a local image for decodeImage().
+       Android 13+ (API 33) uses the scoped media permission; older devices fall
+       back to READ_EXTERNAL_STORAGE (capped at API 32 so the merger doesn't
+       force it on newer OS versions). -->
+  <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
+  <uses-permission
+    android:name="android.permission.READ_EXTERNAL_STORAGE"
+    android:maxSdkVersion="32" />
+
+  <!-- Camera is used but not strictly required (gallery decode works without it). -->
+  <uses-feature
+    android:name="android.hardware.camera"
+    android:required="false" />
+  <uses-feature
+    android:name="android.hardware.camera.autofocus"
+    android:required="false" />
+
+</manifest>

package/android/src/main/java/com/unif/reactnativehmsscan/HmsScanModule.kt

@@ -0,0 +1,192 @@
+package com.unif.reactnativehmsscan
+
+import android.Manifest
+import android.app.Activity
+import android.content.pm.PackageManager
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.net.Uri
+import androidx.core.app.ActivityCompat
+import androidx.core.content.ContextCompat
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.modules.core.PermissionAwareActivity
+import com.facebook.react.modules.core.PermissionListener
+import com.huawei.hms.hmsscankit.ScanUtil
+import com.huawei.hms.ml.scan.HmsScan
+import com.huawei.hms.ml.scan.HmsScanAnalyzerOptions
+import java.io.File
+import java.io.InputStream
+
+/**
+ * TurboModule "HmsScan". Implements the codegen-generated [NativeHmsScanSpec]:
+ *   - decodeImage(): decode a local image into a ScanResult[] JSON string.
+ *   - getCameraPermissionStatus() / requestCameraPermission(): camera permission.
+ */
+class HmsScanModule(reactContext: ReactApplicationContext) :
+  NativeHmsScanSpec(reactContext) {
+
+  override fun getName(): String = NAME
+
+  // ── decodeImage ──────────────────────────────────────────────────────────
+
+  /**
+   * Decode barcodes/QR codes from a local image. Loads the bitmap from a
+   * file:// / content:// URI or an absolute path, runs ScanUtil.decodeWithBitmap
+   * (photo mode), and resolves the ScanResult[] JSON. Never rejects on "no code
+   * found" — it resolves an empty array, matching the JS contract.
+   */
+  override fun decodeImage(uri: String, formatsCsv: String, promise: Promise) {
+    val bitmap = loadBitmap(uri)
+    if (bitmap == null) {
+      promise.reject(E_IMAGE_LOAD_FAILED, "Failed to load image from uri: $uri")
+      return
+    }
+
+    try {
+      val types = HmsScanResultMapper.parseFormatsCsv(formatsCsv)
+      val optionsCreator = HmsScanAnalyzerOptions.Creator().setPhotoMode(true)
+      if (types != null && types.isNotEmpty()) {
+        val first = types.first()
+        val rest = if (types.size > 1) types.copyOfRange(1, types.size) else IntArray(0)
+        optionsCreator.setHmsScanTypes(first, *rest)
+      } else {
+        optionsCreator.setHmsScanTypes(HmsScan.ALL_SCAN_TYPE)
+      }
+      val options = optionsCreator.create()
+
+      val scans = ScanUtil.decodeWithBitmap(reactApplicationContext, bitmap, options)
+      promise.resolve(HmsScanResultMapper.toJson(scans))
+    } catch (e: Throwable) {
+      promise.reject(E_DECODE_FAILED, e.message ?: "Failed to decode image", e)
+    } finally {
+      if (!bitmap.isRecycled) {
+        bitmap.recycle()
+      }
+    }
+  }
+
+  /** Resolve a uri/path to a decoded [Bitmap], or null on any failure. */
+  private fun loadBitmap(uri: String): Bitmap? {
+    return try {
+      val parsed = Uri.parse(uri)
+      val scheme = parsed.scheme?.lowercase()
+      when (scheme) {
+        "content", "file", "android.resource" -> {
+          val resolver = reactApplicationContext.contentResolver
+          var stream: InputStream? = null
+          try {
+            stream = resolver.openInputStream(parsed)
+            if (stream == null) null else BitmapFactory.decodeStream(stream)
+          } finally {
+            stream?.close()
+          }
+        }
+        null -> {
+          // No scheme -> treat as an absolute filesystem path.
+          val path = parsed.path ?: uri
+          decodeFile(path)
+        }
+        else -> {
+          // Unsupported scheme (e.g. http/https): JS contract forbids remote URLs.
+          null
+        }
+      }
+    } catch (e: Throwable) {
+      null
+    }
+  }
+
+  private fun decodeFile(path: String): Bitmap? {
+    val file = File(path)
+    if (!file.exists() || !file.canRead()) return null
+    return BitmapFactory.decodeFile(file.absolutePath)
+  }
+
+  // ── Camera permission ────────────────────────────────────────────────────
+
+  /**
+   * Current camera permission without prompting.
+   *
+   * Note: at query time Android exposes no reliable signal to distinguish
+   * "blocked" / "undetermined" from a plain denial (shouldShowRequestPermissionRationale
+   * is false for both the never-asked and permanently-denied states), so a
+   * not-granted result is reported as "denied". The blocked/undetermined nuance is
+   * resolved by requestCameraPermission() via the post-request rationale check.
+   */
+  override fun getCameraPermissionStatus(promise: Promise) {
+    promise.resolve(if (hasCameraPermission()) GRANTED else DENIED)
+  }
+
+  /**
+   * Request the camera permission (system dialog if needed) and resolve the
+   * resulting status:
+   *   - granted: permission held.
+   *   - denied: rejected but the app may ask again (rationale should be shown).
+   *   - blocked: rejected with "don't ask again" (rationale will not be shown).
+   */
+  override fun requestCameraPermission(promise: Promise) {
+    if (hasCameraPermission()) {
+      promise.resolve(GRANTED)
+      return
+    }
+
+    val activity = currentActivity
+    if (activity == null || activity !is PermissionAwareActivity) {
+      // Can't surface a system dialog without a PermissionAwareActivity; report the
+      // current (not-granted) state rather than hanging the promise.
+      promise.reject(
+        E_NO_ACTIVITY,
+        "Cannot request camera permission: no current PermissionAwareActivity"
+      )
+      return
+    }
+
+    val permissionAwareActivity = activity as PermissionAwareActivity
+    val listener = PermissionListener { requestCode, _, grantResults ->
+      if (requestCode != CAMERA_PERMISSION_REQUEST_CODE) {
+        return@PermissionListener false
+      }
+      val granted = grantResults.isNotEmpty() &&
+        grantResults[0] == PackageManager.PERMISSION_GRANTED
+      val status = when {
+        granted -> GRANTED
+        // After a denial: rationale==true means the user can be asked again;
+        // rationale==false means "don't ask again" (blocked).
+        ActivityCompat.shouldShowRequestPermissionRationale(
+          activity,
+          Manifest.permission.CAMERA
+        ) -> DENIED
+        else -> BLOCKED
+      }
+      promise.resolve(status)
+      true
+    }
+
+    permissionAwareActivity.requestPermissions(
+      arrayOf(Manifest.permission.CAMERA),
+      CAMERA_PERMISSION_REQUEST_CODE,
+      listener
+    )
+  }
+
+  private fun hasCameraPermission(): Boolean =
+    ContextCompat.checkSelfPermission(
+      reactApplicationContext,
+      Manifest.permission.CAMERA
+    ) == PackageManager.PERMISSION_GRANTED
+
+  companion object {
+    const val NAME = NativeHmsScanSpec.NAME
+
+    private const val GRANTED = "granted"
+    private const val DENIED = "denied"
+    private const val BLOCKED = "blocked"
+
+    private const val E_IMAGE_LOAD_FAILED = "E_IMAGE_LOAD_FAILED"
+    private const val E_DECODE_FAILED = "E_DECODE_FAILED"
+    private const val E_NO_ACTIVITY = "E_NO_ACTIVITY"
+
+    private const val CAMERA_PERMISSION_REQUEST_CODE = 0x48_4D // "HM"
+  }
+}

package/android/src/main/java/com/unif/reactnativehmsscan/HmsScanResultMapper.kt

@@ -0,0 +1,145 @@
+package com.unif.reactnativehmsscan
+
+import com.huawei.hms.ml.scan.HmsScan
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Maps HUAWEI Scan Kit [HmsScan] results to the JSON contract shared with the JS
+ * side (see src/format.ts / src/types.ts). Both decodeImage() and the onScanResult
+ * event return a JSON-encoded array of these objects.
+ *
+ * Shape:
+ * ```json
+ * [{"value":"...","format":"EAN_13","contentType":"ARTICLE",
+ *   "cornerPoints":[{"x":10,"y":20}]}]
+ * ```
+ */
+internal object HmsScanResultMapper {
+
+  /**
+   * Serialize an array of [HmsScan] into the ScanResult[] JSON string. The element
+   * type is nullable because the HMS APIs (decodeWithBitmap / OnResultCallback)
+   * hand back a Java array that can contain nulls.
+   */
+  fun toJson(scans: Array<out HmsScan?>?): String {
+    val array = JSONArray()
+    if (scans != null) {
+      for (scan in scans) {
+        if (scan == null) continue
+        val value = scan.getOriginalValue()
+        // A hit with no value is meaningless to the JS layer (it would be dropped
+        // by coerceResult anyway); skip it to keep the payload clean.
+        if (value.isNullOrEmpty()) continue
+        array.put(toJsonObject(scan, value))
+      }
+    }
+    return array.toString()
+  }
+
+  private fun toJsonObject(scan: HmsScan, value: String): JSONObject {
+    val obj = JSONObject()
+    obj.put("value", value)
+    obj.put("format", mapScanType(scan.getScanType()))
+
+    obj.put("contentType", mapContentType(scan.getScanTypeForm()))
+
+    val cornerPoints = scan.getCornerPoints()
+    if (cornerPoints != null && cornerPoints.isNotEmpty()) {
+      val points = JSONArray()
+      for (point in cornerPoints) {
+        if (point == null) continue
+        points.put(
+          JSONObject().apply {
+            put("x", point.x)
+            put("y", point.y)
+          }
+        )
+      }
+      if (points.length() > 0) {
+        obj.put("cornerPoints", points)
+      }
+    }
+
+    return obj
+  }
+
+  /** HmsScan.getScanType() (barcode symbology) -> unified BarcodeFormat string. */
+  fun mapScanType(scanType: Int): String = when (scanType) {
+    HmsScan.QRCODE_SCAN_TYPE -> "QR_CODE"
+    HmsScan.AZTEC_SCAN_TYPE -> "AZTEC"
+    HmsScan.DATAMATRIX_SCAN_TYPE -> "DATA_MATRIX"
+    HmsScan.PDF417_SCAN_TYPE -> "PDF417"
+    HmsScan.CODABAR_SCAN_TYPE -> "CODABAR"
+    HmsScan.CODE39_SCAN_TYPE -> "CODE_39"
+    HmsScan.CODE93_SCAN_TYPE -> "CODE_93"
+    HmsScan.CODE128_SCAN_TYPE -> "CODE_128"
+    HmsScan.EAN8_SCAN_TYPE -> "EAN_8"
+    HmsScan.EAN13_SCAN_TYPE -> "EAN_13"
+    HmsScan.UPCCODE_A_SCAN_TYPE -> "UPC_A"
+    HmsScan.UPCCODE_E_SCAN_TYPE -> "UPC_E"
+    HmsScan.ITF14_SCAN_TYPE -> "ITF14"
+    HmsScan.MULTI_FUNCTIONAL_SCAN_TYPE -> "MULTI_FUNCTIONAL"
+    else -> "UNKNOWN"
+  }
+
+  /**
+   * Resolve a comma-separated formats CSV into the int varargs for
+   * RemoteView.Builder.setFormat / HmsScanAnalyzerOptions.setHmsScanTypes.
+   *
+   * Returns null when the CSV is empty / yields no known formats, signalling the
+   * caller to fall back to [HmsScan.ALL_SCAN_TYPE].
+   */
+  fun parseFormatsCsv(formatsCsv: String?): IntArray? {
+    if (formatsCsv.isNullOrBlank()) return null
+    val types = formatsCsv
+      .split(",")
+      .map { it.trim() }
+      .filter { it.isNotEmpty() }
+      .mapNotNull { mapFormatString(it) }
+      .distinct()
+    return if (types.isEmpty()) null else types.toIntArray()
+  }
+
+  /** Unified BarcodeFormat string -> HmsScan.*_SCAN_TYPE (null when unknown). */
+  private fun mapFormatString(format: String): Int? = when (format) {
+    "QR_CODE" -> HmsScan.QRCODE_SCAN_TYPE
+    "AZTEC" -> HmsScan.AZTEC_SCAN_TYPE
+    "DATA_MATRIX" -> HmsScan.DATAMATRIX_SCAN_TYPE
+    "PDF417" -> HmsScan.PDF417_SCAN_TYPE
+    "CODABAR" -> HmsScan.CODABAR_SCAN_TYPE
+    "CODE_39" -> HmsScan.CODE39_SCAN_TYPE
+    "CODE_93" -> HmsScan.CODE93_SCAN_TYPE
+    "CODE_128" -> HmsScan.CODE128_SCAN_TYPE
+    "EAN_8" -> HmsScan.EAN8_SCAN_TYPE
+    "EAN_13" -> HmsScan.EAN13_SCAN_TYPE
+    "UPC_A" -> HmsScan.UPCCODE_A_SCAN_TYPE
+    "UPC_E" -> HmsScan.UPCCODE_E_SCAN_TYPE
+    "ITF14" -> HmsScan.ITF14_SCAN_TYPE
+    "MULTI_FUNCTIONAL" -> HmsScan.MULTI_FUNCTIONAL_SCAN_TYPE
+    else -> null
+  }
+
+  /**
+   * HmsScan.getScanTypeForm() (content semantic) -> unified BarcodeContentType
+   * string. Unrecognized / generic forms map to "OTHER".
+   *
+   * Uses the named HmsScan.*_FORM constants (public static final ints) rather than
+   * hard-coded numbers so the mapping stays correct across SDK versions.
+   */
+  private fun mapContentType(form: Int): String = when (form) {
+    HmsScan.URL_FORM -> "URL"
+    HmsScan.EMAIL_CONTENT_FORM -> "EMAIL"
+    HmsScan.TEL_PHONE_NUMBER_FORM -> "PHONE"
+    HmsScan.SMS_FORM -> "SMS"
+    HmsScan.WIFI_CONNECT_INFO_FORM -> "WIFI"
+    HmsScan.CONTACT_DETAIL_FORM -> "CONTACT"
+    HmsScan.EVENT_INFO_FORM -> "EVENT"
+    HmsScan.LOCATION_COORDINATE_FORM -> "LOCATION"
+    HmsScan.DRIVER_INFO_FORM -> "DRIVER"
+    HmsScan.ISBN_NUMBER_FORM -> "ISBN"
+    HmsScan.ARTICLE_NUMBER_FORM -> "ARTICLE"
+    HmsScan.PURE_TEXT_FORM -> "TEXT"
+    else -> "OTHER"
+  }
+}