From a3e9a0104d18cd245bfd912d5f8d83f3e5ae2758 Mon Sep 17 00:00:00 2001
From: Jose Olarte III <jose.anomalist.design@gmail.com>
Date: Tue, 30 Jun 2026 11:02:59 +0800
Subject: [PATCH] feat(ios): expose shareId from getSharedImage()

Include the existing native sharedPhotoShareId in the SharedImage
getSharedImage() result so the web layer can identify the current share.
Add shareId to the native result dictionary and plugin response (NSNull on
the no-image branch), and add shareId: string to the TypeScript
SharedImageResult interface.

This surfaces a value that was already produced natively (previously used
only for logging) so application code can later pass it to markProcessed().
No behavior changes beyond exposing the value; Android untouched. Updates
doc/share-target-ios-audit.md accordingly.
---
 doc/share-target-ios-audit.md        | 8 +++++++-
 ios/App/App/SharedImagePlugin.swift  | 8 +++++---
 ios/App/App/SharedImageUtility.swift | 4 ++--
 src/plugins/definitions.ts           | 5 +++++
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/doc/share-target-ios-audit.md b/doc/share-target-ios-audit.md
index 13e9fd53..403a77cd 100644
--- a/doc/share-target-ios-audit.md
+++ b/doc/share-target-ios-audit.md
@@ -44,10 +44,16 @@ The plugin is registered as `SharedImage` and is implemented in:
 
 ### `getSharedImage(): Promise<SharedImageResult | null>`
 
-Returns the shared image as `{ base64, fileName }`, or `null` if none exists.
+Returns the shared image as `{ base64, fileName, shareId }`, or `null` if none
+exists. `shareId` is the native `sharedPhotoShareId` (UUID assigned by the
+Share Extension); pass it to `markProcessed()` to signal explicit completion.
 Read-only: native metadata and the file are left intact after retrieval
 (Phase 1C).
 
+> Note: On iOS the "no shared image" case resolves an object with `base64`,
+> `fileName`, and `shareId` set to `null`; on web `getSharedImage()` resolves
+> `null` directly.
+
 ### `hasSharedImage(): Promise<{ hasImage: boolean }>`
 
 Returns whether a shared image file currently exists, without reading it.
diff --git a/ios/App/App/SharedImagePlugin.swift b/ios/App/App/SharedImagePlugin.swift
index 932a1689..c5966fa3 100644
--- a/ios/App/App/SharedImagePlugin.swift
+++ b/ios/App/App/SharedImagePlugin.swift
@@ -33,7 +33,7 @@ public class SharedImagePlugin: CAPPlugin, CAPBridgedPlugin {
     
     /**
      * Get shared image data from App Group UserDefaults
-     * Returns base64 string and fileName, or null if no image exists
+     * Returns base64 string, fileName, and shareId, or null fields if no image exists
      * Read-only: native metadata and file are left intact after retrieval (Phase 1C)
      */
     @objc public func getSharedImage(_ call: CAPPluginCall) {
@@ -41,7 +41,8 @@ public class SharedImagePlugin: CAPPlugin, CAPBridgedPlugin {
             // No shared image exists - return null (not an error)
             call.resolve([
                 "base64": NSNull(),
-                "fileName": NSNull()
+                "fileName": NSNull(),
+                "shareId": NSNull()
             ])
             return
         }
@@ -49,7 +50,8 @@ public class SharedImagePlugin: CAPPlugin, CAPBridgedPlugin {
         // Return the shared image data
         call.resolve([
             "base64": sharedData["base64"] ?? "",
-            "fileName": sharedData["fileName"] ?? ""
+            "fileName": sharedData["fileName"] ?? "",
+            "shareId": sharedData["shareId"] ?? ""
         ])
     }
     
diff --git a/ios/App/App/SharedImageUtility.swift b/ios/App/App/SharedImageUtility.swift
index 8edab1cc..72cb1b64 100644
--- a/ios/App/App/SharedImageUtility.swift
+++ b/ios/App/App/SharedImageUtility.swift
@@ -44,7 +44,7 @@ public class SharedImageUtility {
      * All images are stored as files for consistency and to avoid UserDefaults size limits
      * Read-only: metadata and file are left intact after retrieval (Phase 1C)
      *
-     * @returns Dictionary with "base64" and "fileName" keys, or nil if no shared image
+     * @returns Dictionary with "base64", "fileName", and "shareId" keys, or nil if no shared image
      */
     static func getSharedImageData() -> [String: String]? {
         let userDefaults = UserDefaults(suiteName: appGroupIdentifier)
@@ -76,7 +76,7 @@ public class SharedImageUtility {
         // Convert file data to base64 for JavaScript consumption
         let base64String = imageData.base64EncodedString()
 
-        return ["base64": base64String, "fileName": fileName]
+        return ["base64": base64String, "fileName": fileName, "shareId": resolvedShareId]
     }
     
     /**
diff --git a/src/plugins/definitions.ts b/src/plugins/definitions.ts
index 31d736fe..a582b8bf 100644
--- a/src/plugins/definitions.ts
+++ b/src/plugins/definitions.ts
@@ -5,6 +5,11 @@
 export interface SharedImageResult {
   base64: string;
   fileName: string;
+  /**
+   * Identifier of the current share (iOS `sharedPhotoShareId`).
+   * Pass this to `markProcessed()` to signal explicit completion.
+   */
+  shareId: string;
 }
 
 export interface SharedImagePlugin {