@pensasystems/pensa-react-native 0.1.0-beta-2

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 PensaSystems
+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/PensaSdkReactNative.podspec

@@ -0,0 +1,25 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "PensaSdkReactNative"
+  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/Pensasystems/pensa-react-native-sdk.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(s)
+  else
+    s.dependency "React-Core"
+  end
+
+  s.dependency "PensaSdk", "~> 1.0.4"
+end

package/README.md

@@ -0,0 +1,373 @@
+# pensa-sdk-react-native
+
+The Pensa Mobile App SDK is a developer toolkit designed to simplify adding Pensa’s capabilities to your mobile applications. It provides pre-built libraries, tools, and APIs to accelerate development and integration, offering streamlined SDK integration, easy initialization, and comprehensive functionality. With the Pensa SDK, you can enhance your app’s features or seamlessly integrate with other services for a cohesive user experience.
+
+## SDK Integration
+
+Integrating the Pensa SDK into your React Native project is simple. Follow the steps below to add the SDK and enable advanced shelf recognition features in your app:
+
+### 1- Install the SDK Package
+Registry: https://www.npmjs.com/package/@pensasystems/pensa-react-native
+
+Add the npm package to your project:
+
+```bash
+npm install @pensasystems/pensa-react-native
+```
+
+or
+
+```bash
+yarn add @pensasystems/pensa-react-native
+```
+
+### 2- Install Native Dependencies (iOS)
+
+After installing the npm package, navigate to the iOS folder and install the native dependencies using CocoaPods:
+
+```bash
+cd ios
+pod install
+```
+
+This step is required for iOS to link the native components of the SDK.
+
+---
+
+Once installation is complete, you can proceed with SDK initialization.
+
+## SDK Initialization
+
+Initializing the Pensa SDK is straightforward. Follow the steps below to set up the SDK with your credentials and start using its features.
+
+### 1- Import and Call initPensa
+
+Call `initPensa()` at the startup of your app, preferably in a root file like `index.js` before calling `AppRegistry.registerComponent`.
+
+```tsx
+import {initPensa} from '@pensasystems/pensa-react-native';
+
+initPensa({
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  isLoggingEnabled: true,
+})
+  .then(() => {
+    console.log('[Pensa] SDK init success');
+  })
+  .catch((error) => {
+    console.log('[Pensa] SDK init error:', error);
+  });
+```
+
+- `clientId` and `clientSecret` are required.
+- `isLoggingEnabled` is optional. When true, internal SDK logs will be printed to console.
+
+If `clientId` or `clientSecret` is missing, initialization will fail.
+
+### 2- Add Listeners (Optional)
+
+To listen to SDK events such as upload progress, success, or failure, you can create a helper hook like below:
+
+```tsx
+// hooks/usePensaListeners.ts
+import {useEffect} from 'react';
+import {PensaEvents} from '@pensasystems/pensa-react-native';
+
+export const usePensaListeners = () => {
+  useEffect(() => {
+    const unsubscribeProgress = PensaEvents.addListener(
+      'onScanUploadProgressUpdate',
+      (e) => {
+        console.log('[Pensa] Progress', e.progress, e.tdlinxId, e.scanAreaId);
+      },
+    );
+
+    const unsubscribeCompleted = PensaEvents.addListener(
+      'onScanUploadCompleted',
+      (e) => {
+        console.log('[Pensa] Completed', e.tdlinxId, e.scanAreaId);
+      },
+    );
+
+    const unsubscribeFailed = PensaEvents.addListener(
+      'onScanUploadFailed',
+      (e) => {
+        console.log('[Pensa] Failed', e.error, e.tdlinxId, e.scanAreaId);
+      },
+    );
+
+    const unsubscribeCantScan = PensaEvents.addListener(
+      'onCantScanReported',
+      (e) => {
+        console.log('[Pensa] CantScan', e.reason, e.tdlinxId, e.scanAreaId);
+      },
+    );
+
+    return () => {
+      unsubscribeProgress();
+      unsubscribeCompleted();
+      unsubscribeFailed();
+      unsubscribeCantScan();
+    };
+  }, []);
+};
+```
+
+Then call the hook in your component:
+
+```tsx
+import {usePensaListeners} from './hooks/usePensaListeners';
+
+usePensaListeners();
+```
+
+> ✅ You should call `usePensaListeners()` **before** `initPensa()`. Calling it after may result in missing early events emitted during SDK initialization.
+
+This will automatically register and clean up all supported event listeners.
+
+---
+
+Once initialized, you can use any of the SDK methods like `showShelfScans`, `showStoresScreen`, or `showScanArea`.
+
+## SDK Functionality
+
+The Pensa library is a lightweight SDK that simplifies interactions through straightforward method calls. This SDK enables you to:
+
+- **Locate stores**: Easily find the stores you're looking for.
+- **Access stores directly**: Use global store IDs to access a specific store and initiate a scan directly.
+- **View store history**: Conveniently access a list of previously visited stores.
+- **Monitor scan uploads**: Track the upload status of your scans.
+
+### Sample Imports
+
+Before using the SDK methods below, make sure to import the required functions:
+
+```tsx
+import {
+  showShelfScans,
+  showProductScans,
+  showStoreSearchView,
+  showStoresScreen,
+  showScanArea,
+  showStockingScreen,
+  showStoreChecklist,
+} from '@pensasystems/pensa-react-native';
+```
+
+### Searching stores
+
+To initiate a store search using the Pensa SDK, integrate the following code snippet:
+
+```tsx
+showStoreSearchView()
+  .catch((error) => {
+    console.log('Error displaying search store:', error);
+  });
+```
+
+This will present a search interface where you can input keywords (e.g., store name, location) to find the desired store. Upon selecting a store from the search results, the SDK will automatically redirect you to that store's details, allowing you to begin a scan.
+
+> The entered keyword must be at least 3 characters long.
+
+### Accessing Stores Directly with Global Store IDs
+
+The Pensa SDK lets you directly access a store and initiate a scan using its global store ID. To do this, use the `showStoreChecklist` method:
+
+```tsx
+showStoreChecklist('example-id')
+  .catch((error) => {
+    console.log('Error displaying store:', error);
+  });
+```
+
+### Sending Custom Parameters with Scans
+
+In addition to using global store IDs, the Pensa SDK allows you to send custom parameters along with your scans. This can be useful for including company-specific information or metadata.
+
+To send custom parameters, use the `sectionKey` and `guid` parameters in the `showStoreChecklist` method.
+
+> It's important to note that both `sectionKey` and `guid` must be used together. If either parameter is missing, the SDK will only consider the `globalStoreId`.
+
+```tsx
+showStoreChecklist('example-id', 'example-guid', 'example-section')
+  .catch((error) => {
+    console.log('Error displaying store:', error);
+  });
+```
+
+### Recently Visited Stores
+
+The Pensa SDK maintains a cache of recently visited stores for easy access and reuse. This allows you to quickly return to a previously scanned store without searching for it again.
+
+#### Adding Stores to the Cache
+
+A store is automatically added to the "Recently Visited Stores" cache when you:
+- Use the `showStoreChecklist()` method to access a store.
+- Select a store from the search results after using `showStoreSearchView()`.
+
+#### Accessing Recently Visited Stores
+
+To display the "Recently Visited Stores" screen, use the following code:
+
+```tsx
+showStoresScreen()
+  .catch((error) => {
+    console.log('Error displaying recently visited stores:', error);
+  });
+```
+
+This will present a screen listing the recently visited stores. You can select a store from this screen to access its details and initiate a new scan.
+
+### Monitoring Scan Uploads
+
+The Pensa SDK provides convenient methods to monitor the progress of your scan uploads. There are two separate methods depending on the type of scan:
+
+#### Shelf Scans
+
+To monitor shelf scan uploads, use the following method:
+
+```tsx
+showShelfScans()
+  .catch((error) => {
+    console.log('Error displaying shelf uploads:', error);
+  });
+```
+
+#### Product Scans
+
+```tsx
+showProductScans()
+  .catch((error) => {
+    console.log('Error displaying product uploads:', error);
+  });
+```
+
+Both methods present a screen that displays the status of each scan upload. You can use these screens to:
+
+- Track upload progress: Observe the progress of ongoing uploads.
+- View completed uploads: See a history of successfully uploaded scans.
+- Cancel uploads: Stop the upload of any scan that is in progress.
+
+These features give you complete control over your scan uploads and ensure you're always informed about their status.
+
+### Stocking Screen
+
+The Pensa SDK allows you to access the stocking screen. This screen is used to review and manage stock actions related to the selected store.
+
+```tsx
+showStockingScreen()
+  .catch((error) => {
+    console.log('Error displaying stocking screen:', error);
+  });
+```
+
+### Scan Area
+
+To directly open a scan area, you must provide a `scanId` and either a `storeId` or a `globalStoreId`.:
+```tsx
+showScanArea(scanId, storeId, globalStoreId)
+  .catch((error) => {
+    console.log('Error displaying scan area:', error);
+  });
+```
+
+This method allows you to navigate directly to a scan area without going through the store selection flow.
+
+# Troubleshooting (Android)
+
+## 1. Core Library Desugaring Required
+
+If you see an error mentioning that `core library desugaring` must be enabled (typically referencing `AAR metadata` or `desugar_jdk_libs`), update your Android project as follows:
+
+### **Step 1 — Add desugaring dependency**
+
+In your app-level `build.gradle`:
+
+```gradle
+dependencies {
+    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'
+}
+```
+
+### **Step 2 — Enable desugaring & set Java 17**
+
+Inside `android { compileOptions { ... } }`:
+
+```gradle
+compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+    coreLibraryDesugaringEnabled true
+}
+```
+
+This configuration is required because the native Pensa Android SDK uses Java 17 language features.
+
+---
+
+## 2. Min SDK Version Requirement
+
+If your Android build fails with a message indicating:
+
+> *minSdkVersion cannot be smaller than 26 for library com.pensasystems:pensasdk*
+
+Then your `minSdkVersion` must be updated.
+
+### **Fix**
+
+In your app-level `build.gradle`:
+
+```gradle
+defaultConfig {
+    minSdkVersion 26
+}
+```
+
+The native Pensa Android SDK requires **minSdk 26**.
+
+---
+
+## 3. Metro Bundler Cannot Connect in Debug Mode (Android Only)
+
+If the Android app cannot connect to Metro (e.g., blank screen, “Unable to load script from assets”), update your debug network rules.
+
+### **Step 1 — Create `network_security_config.xml`**
+
+Create a file:
+
+```
+android/app/src/main/res/xml/network_security_config.xml
+```
+
+With the following content:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="true">10.0.2.2</domain>
+        <domain includeSubdomains="true">localhost</domain>
+        <domain includeSubdomains="true">127.0.0.1</domain>
+    </domain-config>
+</network-security-config>
+```
+
+### **Step 2 — Reference it in `AndroidManifest.xml`**
+
+Inside your `<application>` tag:
+
+```xml
+<application
+    android:networkSecurityConfig="@xml/network_security_config"
+    ... >
+```
+
+This allows the Android emulator to access the React Native bundler during development.
+
+---
+
+### Example Project
+
+For code examples and integration best practices, refer to our GitHub repository.
+

package/android/build.gradle

@@ -0,0 +1,90 @@
+buildscript {
+  ext.getExtOrDefault = {name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['PensaSdkReactNative_' + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+    maven {
+      url = uri("https://sdk.pensasystems.net/pensa-sdk-android")
+    }
+  }
+
+  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"
+
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["PensaSdkReactNative_" + name]).toInteger()
+}
+
+def supportsNamespace() {
+  def parsed = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')
+  def major = parsed[0].toInteger()
+  def minor = parsed[1].toInteger()
+
+  // Namespace support was added in 7.3.0
+  return (major == 7 && minor >= 3) || major >= 8
+}
+
+android {
+  if (supportsNamespace()) {
+    namespace "com.pensasdkreactnative"
+
+    sourceSets {
+      main {
+        manifest.srcFile "src/main/AndroidManifestNew.xml"
+      }
+    }
+  }
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+    coreLibraryDesugaringEnabled true
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+  maven {
+    url = uri("https://sdk.pensasystems.net/pensa-sdk-android")
+  }
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'
+  implementation "com.pensasystems:pensasdk:1.0.8"
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+}
+

package/android/gradle.properties

@@ -0,0 +1,5 @@
+PensaSdkReactNative_kotlinVersion=2.0.21
+PensaSdkReactNative_minSdkVersion=24
+PensaSdkReactNative_targetSdkVersion=34
+PensaSdkReactNative_compileSdkVersion=35
+PensaSdkReactNative_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          package="com.pensasdkreactnative">
+</manifest>

package/android/src/main/AndroidManifestNew.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/pensasdkreactnative/PensaEventEmitterModule.kt

@@ -0,0 +1,21 @@
+package com.pensasdkreactnative
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.modules.core.DeviceEventManagerModule.RCTDeviceEventEmitter
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+
+class PensaEventEmitterModule(private val reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName(): String = "PensaEventEmitter"
+
+  fun sendEvent(eventName: String, params: Map<String, Any?>) {
+    val map: WritableMap = Arguments.makeNativeMap(params)
+    reactContext
+      .getJSModule(RCTDeviceEventEmitter::class.java)
+      .emit(eventName, map)
+  }
+}

package/android/src/main/java/com/pensasdkreactnative/PensaListeners.kt

@@ -0,0 +1,44 @@
+package com.pensasdkreactnative
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.pensasystems.pensasdk.listener.CantScanEventListener
+import com.pensasystems.pensasdk.listener.ScanUploadListener
+
+object PensaListeners : ScanUploadListener, CantScanEventListener {
+
+  private var emitter: PensaEventEmitterModule? = null
+
+  fun setup(reactContext: ReactApplicationContext) {
+    emitter = PensaEventEmitterModule(reactContext)
+  }
+
+  override fun onScanUploadCompleted(tdlinxId: String, scanAreaId: String) {
+    emitter?.sendEvent("onScanUploadCompleted", mapOf(
+      "tdlinxId" to tdlinxId,
+      "scanAreaId" to scanAreaId
+    ))
+  }
+
+  override fun onScanUploadFailed(tdlinxId: String, scanAreaId: String) {
+    emitter?.sendEvent("onScanUploadFailed", mapOf(
+      "tdlinxId" to tdlinxId,
+      "scanAreaId" to scanAreaId
+    ))
+  }
+
+  override fun onScanUploadProgressUpdate(tdlinxId: String, scanAreaId: String, progress: Int) {
+    emitter?.sendEvent("onScanUploadProgressUpdate", mapOf(
+      "tdlinxId" to tdlinxId,
+      "scanAreaId" to scanAreaId,
+      "progress" to progress
+    ))
+  }
+
+  override fun onCantScanReported(tdlinxId: String, scanAreaId: String, cantScanReason: String) {
+    emitter?.sendEvent("onCantScanReported", mapOf(
+      "tdlinxId" to tdlinxId,
+      "scanAreaId" to scanAreaId,
+      "reason" to cantScanReason
+    ))
+  }
+}