@sparkvault/sdk-mobile 6.0.0 → 6.0.1

package/dist/types.d.ts

@@ -708,13 +708,25 @@ export interface UploadTransferPolicy {
  */
 export type UploadAbortBehavior = 'terminate' | 'keep';
 /**
- * App-provided adapter that PATCHes a whole local file as the request body
- * on a background URLSession (expo-file-system legacy `uploadAsync` with
- * `sessionType: BACKGROUND`), so a single-chunk upload finishes even when iOS
- * suspends the app mid-transfer. The fallback behind `backgroundTransfer`:
- * the tus uploader reaches for it only when no OS transfer engine is
- * configured and the file fits one chunk; everything else keeps the
- * streaming XHR path.
+ * App-provided adapter that PATCHes a whole local file as the request body.
+ * The fallback behind `backgroundTransfer`: the tus uploader reaches for it
+ * only when no OS transfer engine is configured and the file fits one chunk;
+ * everything else keeps the streaming XHR path.
+ *
+ * The SDK does not ask for an OS background session here, and a host should
+ * think twice before backing this with one. A background session hands the
+ * body's path to a system daemon that opens the file in its own process,
+ * outside whatever sandbox extensions the app holds; a file the app can read
+ * is not necessarily one the daemon can. Where `fileUri` may point outside
+ * the app's container - a photo library original, a document-picker result -
+ * a background session fails at open() before a byte moves, and reports it
+ * as a transport error indistinguishable from a dead connection. A host that
+ * wants suspension-survival should stage the body into its own container
+ * first, the way the OS transfer engine does, or supply
+ * `backgroundTransfer` instead. Note that opting out can take an explicit
+ * flag: expo-file-system's `uploadAsync` writes `sessionType: BACKGROUND`
+ * into its options before spreading the caller's, so omitting the key selects
+ * a background session rather than declining one.
  */
 export interface MobileBackgroundUploader {
     uploadFile(url: string, fileUri: string, options: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkvault/sdk-mobile",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "description": "Mobile SDK for SparkVault Identity, vault, folder, and ingot workflows",
   "type": "module",
   "main": "./dist/index.js",

package/src/types.ts

@@ -811,13 +811,25 @@ export interface UploadTransferPolicy {
 export type UploadAbortBehavior = 'terminate' | 'keep';
 
 /**
- * App-provided adapter that PATCHes a whole local file as the request body
- * on a background URLSession (expo-file-system legacy `uploadAsync` with
- * `sessionType: BACKGROUND`), so a single-chunk upload finishes even when iOS
- * suspends the app mid-transfer. The fallback behind `backgroundTransfer`:
- * the tus uploader reaches for it only when no OS transfer engine is
- * configured and the file fits one chunk; everything else keeps the
- * streaming XHR path.
+ * App-provided adapter that PATCHes a whole local file as the request body.
+ * The fallback behind `backgroundTransfer`: the tus uploader reaches for it
+ * only when no OS transfer engine is configured and the file fits one chunk;
+ * everything else keeps the streaming XHR path.
+ *
+ * The SDK does not ask for an OS background session here, and a host should
+ * think twice before backing this with one. A background session hands the
+ * body's path to a system daemon that opens the file in its own process,
+ * outside whatever sandbox extensions the app holds; a file the app can read
+ * is not necessarily one the daemon can. Where `fileUri` may point outside
+ * the app's container - a photo library original, a document-picker result -
+ * a background session fails at open() before a byte moves, and reports it
+ * as a transport error indistinguishable from a dead connection. A host that
+ * wants suspension-survival should stage the body into its own container
+ * first, the way the OS transfer engine does, or supply
+ * `backgroundTransfer` instead. Note that opting out can take an explicit
+ * flag: expo-file-system's `uploadAsync` writes `sessionType: BACKGROUND`
+ * into its options before spreading the caller's, so omitting the key selects
+ * a background session rather than declining one.
  */
 export interface MobileBackgroundUploader {
   uploadFile(