@yeomessagingcom/react-native-yeofr 0.1.12 → 0.1.14

package/README.md

@@ -6,4 +6,30 @@ iOS face recognition bridge for React Native (device-only).
 ## Install
 ```bash
 npm i @yeomessaging/react-native-yeofr
-cd ios && pod install && cd ..
+cd ios && pod install && cd ..
+```
+
+## Bumping npm module version:
+1. update s.version in podspec with the new version number
+2. update "version" in package.json with the new version number
+
+if need to update SPM version that is used for framework asset:
+1. update bin_ver in podspec
+2. update sha256 with checksum from spm in podspec
+
+## Publishing:
+1. deprecate previous version (if required) (NB 0.1.11 is an example):
+```bash
+npm deprecate @yeomessagingcom/react-native-yeofr@0.1.11 "Deprecated"
+```
+
+2. tag with lastest version (NB 0.1.12 is an example - use the real next version of the nom module):
+```bash
+git tag 0.1.12  
+git push --tags
+```
+
+3. publish
+```bash
+npm publish --access public
+```

package/ios/YEOFR.xcframework/Info.plist

@@ -0,0 +1,27 @@
+<?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>AvailableLibraries</key>
+	<array>
+		<dict>
+			<key>BinaryPath</key>
+			<string>YEOFR.framework/YEOFR</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64</string>
+			<key>LibraryPath</key>
+			<string>YEOFR.framework</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+		</dict>
+	</array>
+	<key>CFBundlePackageType</key>
+	<string>XFWK</string>
+	<key>XCFrameworkFormatVersion</key>
+	<string>1.0</string>
+</dict>
+</plist>

package/ios/YEOFR.xcframework/ios-arm64/YEOFR.framework/Headers/YEOFR.h

@@ -0,0 +1,18 @@
+//
+//  YEOFR.h
+//  YEOFR
+//
+//  Created by paul calver on 22/08/2025.
+//
+
+#import <Foundation/Foundation.h>
+
+//! Project version number for YEOFR.
+FOUNDATION_EXPORT double YEOFRVersionNumber;
+
+//! Project version string for YEOFR.
+FOUNDATION_EXPORT const unsigned char YEOFRVersionString[];
+
+// In this header, you should import all the public headers of your framework using statements like #import <YEOFR/PublicHeader.h>
+
+#import <YEOFR/YEOFRBridge.h>

package/ios/YEOFR.xcframework/ios-arm64/YEOFR.framework/Headers/YEOFRBridge.h

@@ -0,0 +1,261 @@
+//
+//  YEOFRBridge.h
+//  YEOFR
+//
+//  Created by paul calver on 02/09/2025.
+//
+
+
+//#ifndef YEOFRBridge_h
+//#define YEOFRBridge_h
+//
+//
+//#endif /* YEOFRBridge_h */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+FOUNDATION_EXPORT NSErrorDomain const FRSDKErrorDomain;
+
+typedef NS_ENUM(NSInteger, FRSDKReturnCode) {
+    FRSDKReturnCodeOK                                  = 0,
+    FRSDKReturnCodeFailed                              = -1,
+    FRSDKReturnCodeNotActivated                        = -2,
+    FRSDKReturnCodeOutOfMemory                         = -3,
+    FRSDKReturnCodeInvalidArgument                     = -4,
+    FRSDKReturnCodeIOError                             = -5,
+    FRSDKReturnCodeImageTooSmall                       = -6,
+    FRSDKReturnCodeFaceNotFound                        = -7,
+    FRSDKReturnCodeInsufficientBufferSize              = -8,
+    FRSDKReturnCodeUnsupportedImageExtension           = -9,
+    FRSDKReturnCodeCannotOpenFile                      = -10,
+    FRSDKReturnCodeCannotCreateFile                    = -11,
+    FRSDKReturnCodeBadFileFormat                       = -12,
+    FRSDKReturnCodeFileNotFound                        = -13,
+    FRSDKReturnCodeConnectionClosed                    = -14,
+    FRSDKReturnCodeConnectionFailed                    = -15,
+    FRSDKReturnCodeIPInitFailed                        = -16,
+    FRSDKReturnCodeNeedServerActivation                = -17,
+    FRSDKReturnCodeIdNotFound                          = -18,
+    FRSDKReturnCodeAttributeNotDetected                = -19,
+    FRSDKReturnCodeInsufficientTrackerMemoryLimit      = -20,
+    FRSDKReturnCodeUnknownAttribute                    = -21,
+    FRSDKReturnCodeUnsupportedFileVersion              = -22,
+    FRSDKReturnCodeSyntaxError                         = -23,
+    FRSDKReturnCodeParameterNotFound                   = -24,
+    FRSDKReturnCodeInvalidTemplate                     = -25,
+    FRSDKReturnCodeUnsupportedTemplateVersion          = -26,
+    FRSDKReturnCodeCameraIndexDoesNotExist             = -27,
+    FRSDKReturnCodePlatformNotLicensed                 = -28,
+    FRSDKReturnCodeTensorflowNotInitialized            = -29,
+    FRSDKReturnCodePluginNotLoaded                     = -30,
+    FRSDKReturnCodePluginNoPermission                  = -31,
+    FRSDKReturnCodeTrackerIsNull                       = -32,
+    FRSDKReturnCodeBufferSizeInvalid                   = -33,
+    FRSDKReturnCodeTrackerBufferMallocFailed           = -34,
+    FRSDKReturnCodeOutTrackerNull                      = -35,
+    FRSDKReturnCodeEmptyTrackerData                    = -36,
+    FRSDKReturnCodeSetParametersFailed                 = -37,
+    FRSDKReturnCodeTrackerExists                       = -38,
+};
+
+@interface YEOFRBridge : NSObject
+
++ (NSString *)stringForReturnCode:(FRSDKReturnCode)rc;
+/// ---------------------------------------------------------------------
+/// @name SDK Activation / Queries
+/// ---------------------------------------------------------------------
+
+/// Activate and initialize the SDK.
+///
+/// @param key      License/activation key provided by the vendor.
+/// @param dataPath Optional path to SDK data/resources (pass `nil` if not required by your build).
+/// @param error    Populated on failure with an NSError describing the underlying SDK error.
+///
+/// @return FRSDKReturnCode.
+///
+/// @discussion Call this once during app startup (before using any tracker APIs).
++ (FRSDKReturnCode)activateWithKey:(NSString *)key
+               dataPath:(NSString * _Nullable)dataPath
+                  error:(NSError * _Nullable * _Nullable)error;
+
+/// Get a device hardware identifier from the SDK (smoke test).
+///
+/// @param outHardwareID On success, receives a hardware ID string. Nil on failure.
+/// @param error         Populated on failure with an NSError describing the SDK error.
+///
+/// @return FRSDKReturnCode.
++ (FRSDKReturnCode)getHardwareID:(NSString * __autoreleasing _Nullable * _Nullable)outHardwareID
+                error:(NSError * _Nullable * _Nullable)error;
+
+/// Retrieve license information from the SDK (optional).
+///
+/// @param outLicenseInfo On success, receives a human-readable license string. Nil on failure.
+/// @param error          Populated on failure with an NSError describing the SDK error.
+///
+/// @return FRSDKReturnCode.
++ (FRSDKReturnCode)getLicenseInfo:(NSString * __autoreleasing _Nullable * _Nullable)outLicenseInfo
+                 error:(NSError * _Nullable * _Nullable)error;
+
+/// ---------------------------------------------------------------------
+/// @name Frame Processing
+/// ---------------------------------------------------------------------
+
+/// Process a single ARGB32 frame through the SDK pipeline.
+///
+/// Steps performed:
+///  1. Load image from buffer
+///  2. Mirror image horizontally
+///  3. Feed tracker
+///  4. Retrieve names per ID
+///  5. (Optional) Estimate face rect from tracker eyes
+///
+/// @param buffer        Pointer to ARGB32 pixel data (compatible with FSDK_LoadImageFromBuffer).
+/// @param width         Frame width in pixels.
+/// @param height        Frame height in pixels.
+/// @param scanLine      Bytes per row (stride).
+/// @param tracker       Tracker handle (`HTracker`) as `int64_t`.
+/// @param needFaceRect  If YES, computes face rects (additional per-face call).
+/// @param ratio         Scale factor to apply to rects (mirrors your Swift `imageFrameParameters.ratio`).
+/// @param outIDs        On success, receives an NSArray<NSNumber*> of face IDs (Int64).
+/// @param outNames      On success, receives an NSDictionary<NSNumber*, NSString*> mapping ID → name (empty string or absence means not enrolled).
+/// @param outRects      On success, receives an NSDictionary<NSNumber*, NSValue(CGRect)> mapping ID → face rect (image coordinates).
+/// @param outDetectedCount On success, receives the number of detected faces.
+/// @param error         Populated on failure with an NSError describing the SDK error.
+///
+/// @return FRSDKReturnCode.
+///
+/// @note The `buffer` memory is owned by the caller and must remain valid for the call duration.
++ (FRSDKReturnCode)processFrameWithBuffer:(const void *)buffer
+                         width:(int)width
+                        height:(int)height
+                      scanLine:(int)scanLine
+                       tracker:(int64_t)tracker
+                  needFaceRect:(BOOL)needFaceRect
+                         ratio:(float)ratio
+                        outIDs:(NSArray<NSNumber *> * __autoreleasing _Nullable * _Nullable)outIDs
+                      outNames:(NSDictionary<NSNumber *, NSString *> * __autoreleasing _Nullable * _Nullable)outNames
+                      outRects:(NSDictionary<NSNumber *, NSValue *> * __autoreleasing _Nullable * _Nullable)outRects
+               outDetectedCount:(NSInteger * _Nullable)outDetectedCount
+                         error:(NSError * __autoreleasing _Nullable * _Nullable)error;
+
+/// ---------------------------------------------------------------------
+/// @name Tracker Lifecycle
+/// ---------------------------------------------------------------------
+
+/// Create a new tracker.
+///
+/// @param outTracker On success, receives the newly created tracker handle (`HTracker` as `int64_t`).
+/// @param error      Populated on failure with an NSError describing the SDK error.
+///
+/// @return FRSDKReturnCode.
++ (FRSDKReturnCode)createTracker:(int64_t * _Nonnull)outTracker
+                error:(NSError * _Nullable * _Nullable)error;
+
+/// Free a tracker.
+///
+/// @param tracker Tracker handle to free (`HTracker` as `int64_t`). If 0, this is a no-op.
+/// @param error   Populated on unexpected failure (usually unused; SDK free often returns void).
+///
+/// @return FRSDKReturnCode.
++ (FRSDKReturnCode)freeTracker:(int64_t)tracker
+              error:(NSError * _Nullable * _Nullable)error;
+
+/// ---------------------------------------------------------------------
+/// @name Enrollment
+/// ---------------------------------------------------------------------
+
+/// Assign a name (tag) to a face ID in the tracker.
+///
+/// @param tracker Tracker handle (`HTracker` as `int64_t`).
+/// @param faceID  Face ID to name.
+/// @param name    Display name/tag to assign. Empty string may be treated as removal by the SDK.
+/// @param error   Populated on failure with an NSError describing the SDK error.
+///
+/// @return FRSDKReturnCode.
+///
+/// @note Typical flow: `LockID` → `SetName` → (optional) `LearnCurrentFace` → `UnlockID`.
++ (FRSDKReturnCode)setName:(int64_t)tracker
+         faceID:(long long)faceID
+           name:(NSString *)name
+          error:(NSError * _Nullable * _Nullable)error;
+
+/// Learn/improve the current face template (optional helper).
+///
+/// @param tracker Tracker handle (`HTracker` as `int64_t`).
+/// @param error   Populated on failure with an NSError describing the SDK error.
+///
+/// @return FRSDKReturnCode
++ (FRSDKReturnCode)learnCurrentFace:(int64_t)tracker
+                   error:(NSError * _Nullable * _Nullable)error;
+
+/// ---------------------------------------------------------------------
+/// @name Tracker (Memory) Serialization
+/// ---------------------------------------------------------------------
+
+/// Get the current tracker as an in-memory blob.
+///
+/// @param tracker Tracker handle (`HTracker` as `int64_t`).
+/// @param outData On success, receives NSData containing the serialized tracker.
+/// @param error   Populated on failure with an NSError describing the SDK error.
+///
+/// @return FRSDKReturnCode.
+///
+/// @discussion Use this to persist the tracker (e.g., write `outData` to file or upload).
++ (FRSDKReturnCode)getTrackerData:(int64_t)tracker
+               outData:(NSData * _Nullable * _Nullable)outData
+                 error:(NSError * _Nullable * _Nullable)error;
+
+/// Load a tracker from an in-memory blob.
+///
+/// @param data       NSData previously obtained from `getTrackerData:outData:error:`.
+/// @param outTracker On success, receives a new tracker handle (`HTracker` as `int64_t`).
+/// @param error      Populated on failure with an NSError describing the SDK error.
+///
+/// @return FRSDKReturnCode.
+///
+/// @note The caller is responsible for freeing any previously held tracker before swapping in the returned handle.
++ (FRSDKReturnCode)loadTrackerFromData:(NSData *)data
+                 outTracker:(int64_t * _Nonnull)outTracker
+                      error:(NSError * _Nullable * _Nullable)error;
+
+/// ---------------------------------------------------------------------
+/// @name Tracker / Global Configuration
+/// ---------------------------------------------------------------------
+
+/// Apply tracker parameters from an FRSDK-formatted parameter string.
+///
+/// @param tracker   Tracker handle (`HTracker` as `int64_t`).
+/// @param params    Parameter string (same format as `config.asTrackerParameters`).
+/// @param outErrPos Receives the 1-based position of the first error in the string; 0 on success.
+/// @param error     If `outErrPos != 0`, also populated with a descriptive NSError.
+///
+/// @return FRSDKReturnCode.
+///
+/// @discussion Wraps `FSDK_SetTrackerMultipleParameters`. Useful to atomically set multiple
+/// parameters; check `outErrPos` for the failing position if NO is returned.
++ (FRSDKReturnCode)setTrackerParameters:(int64_t)tracker
+                   paramsUTF8:(NSString *)params
+            outErrorPosition:(int32_t * _Nullable)outErrPos
+                       error:(NSError * _Nullable * _Nullable)error;
+
+/// Configure global SDK parameters.
+///
+/// @param threads       Number of threads for the SDK to use.
+/// @param resizeWidth   Internal resize width for detection (see vendor docs).
+/// @param threshold     Detection threshold (higher is stricter).
+/// @param error         Populated on failure with an NSError describing the SDK error.
+///
+/// @return FRSDKReturnCode.
+///
+/// @discussion Applies common global knobs such as thread count and detection parameters.
+/// Call this early (e.g., after activation) and whenever configuration changes.
++ (FRSDKReturnCode)configureWithThreads:(int32_t)threads
+         internalResizeWidth:(int32_t)resizeWidth
+          detectionThreshold:(int32_t)threshold
+                       error:(NSError * _Nullable * _Nullable)error;
+
+@end
+
+NS_ASSUME_NONNULL_END