@velion-la/onboarding-sdk-react-native 1.2.0-beta.0 → 1.2.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +47 -17
  2. package/lib/commonjs/camera/DocumentCapture.js +57 -35
  3. package/lib/commonjs/camera/DocumentCapture.js.map +1 -1
  4. package/lib/commonjs/camera/LivenessCamera.js +137 -86
  5. package/lib/commonjs/camera/LivenessCamera.js.map +1 -1
  6. package/lib/commonjs/camera/MapAddressPicker.js +1 -1
  7. package/lib/commonjs/camera/MapAddressPicker.js.map +1 -1
  8. package/lib/commonjs/steps/DocumentsOcrStep.js +140 -20
  9. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  10. package/lib/commonjs/steps/LivenessMatchStep.js +101 -39
  11. package/lib/commonjs/steps/LivenessMatchStep.js.map +1 -1
  12. package/lib/commonjs/transport/irisWebSocket.js +38 -3
  13. package/lib/commonjs/transport/irisWebSocket.js.map +1 -1
  14. package/lib/commonjs/ui/icons/StepIcon.js +8 -3
  15. package/lib/commonjs/ui/icons/StepIcon.js.map +1 -1
  16. package/lib/commonjs/ui/overlays/LoadingOverlay.js +1 -1
  17. package/lib/commonjs/ui/overlays/LoadingOverlay.js.map +1 -1
  18. package/lib/commonjs/ui/overlays/RetryDialog.js +1 -1
  19. package/lib/commonjs/ui/overlays/RetryDialog.js.map +1 -1
  20. package/lib/commonjs/utils/jpegFromUri.js +54 -14
  21. package/lib/commonjs/utils/jpegFromUri.js.map +1 -1
  22. package/lib/module/camera/DocumentCapture.js +58 -36
  23. package/lib/module/camera/DocumentCapture.js.map +1 -1
  24. package/lib/module/camera/LivenessCamera.js +138 -87
  25. package/lib/module/camera/LivenessCamera.js.map +1 -1
  26. package/lib/module/camera/MapAddressPicker.js +1 -1
  27. package/lib/module/camera/MapAddressPicker.js.map +1 -1
  28. package/lib/module/steps/DocumentsOcrStep.js +140 -20
  29. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  30. package/lib/module/steps/LivenessMatchStep.js +102 -40
  31. package/lib/module/steps/LivenessMatchStep.js.map +1 -1
  32. package/lib/module/transport/irisWebSocket.js +38 -3
  33. package/lib/module/transport/irisWebSocket.js.map +1 -1
  34. package/lib/module/ui/icons/StepIcon.js +8 -3
  35. package/lib/module/ui/icons/StepIcon.js.map +1 -1
  36. package/lib/module/ui/overlays/LoadingOverlay.js +1 -1
  37. package/lib/module/ui/overlays/LoadingOverlay.js.map +1 -1
  38. package/lib/module/ui/overlays/RetryDialog.js +1 -1
  39. package/lib/module/ui/overlays/RetryDialog.js.map +1 -1
  40. package/lib/module/utils/jpegFromUri.js +52 -14
  41. package/lib/module/utils/jpegFromUri.js.map +1 -1
  42. package/lib/typescript/camera/DocumentCapture.d.ts +15 -3
  43. package/lib/typescript/camera/DocumentCapture.d.ts.map +1 -1
  44. package/lib/typescript/camera/LivenessCamera.d.ts +35 -9
  45. package/lib/typescript/camera/LivenessCamera.d.ts.map +1 -1
  46. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  47. package/lib/typescript/steps/LivenessMatchStep.d.ts.map +1 -1
  48. package/lib/typescript/transport/irisWebSocket.d.ts.map +1 -1
  49. package/lib/typescript/ui/icons/StepIcon.d.ts +7 -2
  50. package/lib/typescript/ui/icons/StepIcon.d.ts.map +1 -1
  51. package/lib/typescript/utils/jpegFromUri.d.ts +31 -10
  52. package/lib/typescript/utils/jpegFromUri.d.ts.map +1 -1
  53. package/package.json +20 -14
  54. package/src/camera/DocumentCapture.tsx +59 -41
  55. package/src/camera/LivenessCamera.tsx +159 -86
  56. package/src/camera/MapAddressPicker.tsx +1 -1
  57. package/src/steps/DocumentsOcrStep.tsx +160 -18
  58. package/src/steps/LivenessMatchStep.tsx +112 -47
  59. package/src/transport/irisWebSocket.ts +32 -2
  60. package/src/ui/icons/StepIcon.tsx +9 -3
  61. package/src/ui/overlays/LoadingOverlay.tsx +1 -1
  62. package/src/ui/overlays/RetryDialog.tsx +1 -1
  63. package/src/utils/jpegFromUri.ts +54 -16
@@ -2,12 +2,23 @@
2
2
  * @fileoverview Liveness camera surface — front-facing vision-camera with an
3
3
  * oval mask, status pill, and capture loop driven by the parent step.
4
4
  *
5
- * Capture strategy: vision-camera v4 frame processors run on a worklet thread
6
- * and don't expose the JPEG bytes back to JS without a custom native plugin.
7
- * We avoid that complication by using `takePhoto({ qualityPrioritization:
8
- * 'speed' })` on a JS-level interval (matches the `setInterval` pattern in
9
- * `web/LivenessModule.ts`). Real-world FPS lands around 3–8 fps which is
10
- * sufficient for Iris's challenge cadence.
5
+ * Capture strategy: the web SDK grabs JPEG frames from the live video
6
+ * element. We do the Android equivalent: `takeSnapshot()` of the preview
7
+ * (the same pixels the user framed in the oval). Still-photo capture on
8
+ * the same session as the evidence recorder produced blurry JPEGs that
9
+ * Iris rejected as `LOW_SHARPNESS` and MiniFAS scored as a screen replay.
10
+ *
11
+ * `takeSnapshot()` is Android-only. iOS falls back to a photo output with
12
+ * `qualityPrioritization: 'quality'` (not `'speed'` — that is ZSL and
13
+ * starves when video is running).
14
+ *
15
+ * Preview snapshots are selfie-mirrored. We un-mirror before encoding so
16
+ * Iris sees real-world yaw (OSDKR-23). The on-screen preview stays mirrored.
17
+ *
18
+ * NOTE: the preview is deliberately NOT in `<Camera outputs={...}>`.
19
+ * `<Camera>` creates its own and prepends it (`outputs: [previewOutput,
20
+ * ...outputs]`); passing one explicitly adds a duplicate preview connection
21
+ * that the session refuses (OSDKR-20).
11
22
  *
12
23
  * The parent owns the loop and the WebSocket — this component just exposes a
13
24
  * `captureFrame` ref so the step can drive the timing while the camera stays
@@ -34,16 +45,35 @@ import {
34
45
  import Svg, { Defs, Ellipse, Mask, Rect } from 'react-native-svg';
35
46
  import {
36
47
  Camera,
48
+ CommonResolutions,
37
49
  useCameraDevice,
38
- useCameraFormat,
39
50
  useCameraPermission,
51
+ usePhotoOutput,
52
+ useVideoOutput,
53
+ type CameraRef,
40
54
  type PhotoFile,
41
- type VideoFile,
55
+ type Recorder,
42
56
  } from 'react-native-vision-camera';
43
57
  import { Button } from '../ui/primitives/Button';
44
58
  import { useTheme, withAlpha } from '../ui/theme';
45
59
  import { useSafeAreaInsets } from '../utils/useSafeAreaInsets';
46
60
 
61
+ /**
62
+ * The recorded liveness video, as this component reports it upwards.
63
+ *
64
+ * vision-camera v5 hands `onRecordingFinished` a bare file path, while the
65
+ * upload pipeline also wants the duration for the `liveness-verify` metadata.
66
+ * We read the duration off the `Recorder` before finalising and re-assemble
67
+ * both here, so the step keeps consuming one object instead of two loose
68
+ * values.
69
+ */
70
+ export interface LivenessVideoFile {
71
+ /** Filesystem path, not a `file://` URL. */
72
+ path: string;
73
+ /** Recorded duration in seconds, or `undefined` when it could not be read. */
74
+ duration?: number | undefined;
75
+ }
76
+
47
77
  export interface LivenessCameraHandle {
48
78
  takeFrame: () => Promise<PhotoFile | null>;
49
79
  /**
@@ -54,9 +84,9 @@ export interface LivenessCameraHandle {
54
84
  * even when this fails.
55
85
  */
56
86
  startVideoRecording(opts: {
57
- onRecordingFinished: (video: VideoFile) => void;
87
+ onRecordingFinished: (video: LivenessVideoFile) => void;
58
88
  onRecordingError: (err: unknown) => void;
59
- }): void;
89
+ }): Promise<void>;
60
90
  /**
61
91
  * Stop the active recording. Resolves once `onRecordingFinished` has been
62
92
  * scheduled by vision-camera; the file path arrives there, not here.
@@ -97,18 +127,50 @@ export const LivenessCamera = forwardRef<LivenessCameraHandle, LivenessCameraPro
97
127
  function LivenessCamera(props, ref) {
98
128
  const theme = useTheme();
99
129
  const insets = useSafeAreaInsets();
100
- const cameraRef = useRef<Camera>(null);
130
+ const cameraRef = useRef<CameraRef>(null);
101
131
  const device = useCameraDevice('front');
102
- // Pick a 720p / 30-fps format so the recorded mp4 stays a few MB instead
103
- // of the device-default 1080p–4K bitrate (a 30 s session can otherwise
104
- // produce a 50–80 MB file that times out on mobile uplinks). The face
105
- // visibility for liveness evidence is fine at 720p. Constraints are
106
- // ordered by priority — vision-camera picks the closest match.
107
- const format = useCameraFormat(device, [
108
- { videoResolution: { width: 1280, height: 720 } },
109
- { fps: 30 },
110
- { videoStabilizationMode: 'off' },
111
- ]);
132
+ // Stills at MAXIMIZE_QUALITY, used on iOS and on Android unless the switch
133
+ // above selects the preview snapshot.
134
+ // Capture WELL ABOVE the wire size on purpose (OSDKR-23).
135
+ //
136
+ // Iris scores sharpness as the Laplacian variance of the face region in
137
+ // the frame we send, and that number depends on how much we downscaled to
138
+ // get there. Downsampling concentrates detail and averages out sensor
139
+ // noise, so a 720 px frame derived from a large capture is measurably
140
+ // sharper than one captured at ~720 px natively.
141
+ //
142
+ // The spike had this at HD_4_3 (768x1024), reasoning that the frame gets
143
+ // resized to 720 anyway. It does — but that is a 0.94x scale, which keeps
144
+ // all of the lens softness and noise reduction of the native capture. On a
145
+ // Motorola Edge 30 Neo it measured `sharpness_quality` 0.16 average and
146
+ // 0.216 peak against a 0.35 threshold, with good lighting and a 312x470 px
147
+ // face: not a framing problem, a resolution one.
148
+ //
149
+ // FHD_4_3 gives a 2x linear downscale to the 720 px wire size at a
150
+ // fraction of the cost of the 12 MP default. Escalate to
151
+ // `CommonResolutions.UHD_4_3` — what iOS used when it passed the gate — if
152
+ // the measured sharpness is still short.
153
+ const photoOutput = usePhotoOutput({
154
+ qualityPrioritization: 'quality',
155
+ targetResolution: CommonResolutions.FHD_4_3,
156
+ quality: 0.9,
157
+ });
158
+ // Pin the recording to 720p so the mp4 stays a few MB instead of the
159
+ // device-default 1080p–4K bitrate (a 30 s session can otherwise produce a
160
+ // 50–80 MB file that times out on mobile uplinks). Face visibility for
161
+ // liveness evidence is fine at 720p. Audio off — the backend never uses it
162
+ // and recording it would demand the microphone permission.
163
+ const videoOutput = useVideoOutput({
164
+ targetResolution: CommonResolutions.HD_16_9,
165
+ // ~2 Mbps. NOTE the unit: v5 takes bits per second, where v4's
166
+ // `videoBitRate` prop took megabits — passing `2` here would ask for
167
+ // 2 bps and produce an unusable file. The device default (~8 Mbps at
168
+ // 720p) yields a 38 MB file for a 30 s session; ~2 Mbps is plenty for
169
+ // face visibility as compliance evidence and lands around 7–8 MB.
170
+ targetBitRate: 2_000_000,
171
+ enableAudio: false,
172
+ fileType: 'mp4',
173
+ });
112
174
  const { hasPermission, requestPermission } = useCameraPermission();
113
175
  const requestedRef = useRef(false);
114
176
  const inFlightRef = useRef(false);
@@ -134,14 +196,12 @@ export const LivenessCamera = forwardRef<LivenessCameraHandle, LivenessCameraPro
134
196
 
135
197
  const takeFrame = useCallback(async (): Promise<PhotoFile | null> => {
136
198
  if (inFlightRef.current) return null;
137
- const camera = cameraRef.current;
138
- if (!camera) return null;
139
199
  inFlightRef.current = true;
140
200
  try {
141
- return await camera.takePhoto({
142
- flash: 'off',
143
- enableShutterSound: false,
144
- });
201
+ return await photoOutput.capturePhotoToFile(
202
+ { flashMode: 'off', enableShutterSound: false },
203
+ {},
204
+ );
145
205
  } catch {
146
206
  // Frame failures are non-fatal — the parent loop just retries on the
147
207
  // next tick. Keep the camera mounted.
@@ -149,47 +209,71 @@ export const LivenessCamera = forwardRef<LivenessCameraHandle, LivenessCameraPro
149
209
  } finally {
150
210
  inFlightRef.current = false;
151
211
  }
152
- }, []);
212
+ }, [photoOutput]);
153
213
 
154
- // Recording is best-effort and orthogonal to the frame loop. We track an
155
- // `isRecording` flag so `stopVideoRecording` is idempotent even if the
156
- // parent calls it twice (e.g. on SESSION_COMPLETE and again on unmount).
157
- const recordingRef = useRef(false);
214
+ // Recording is best-effort and orthogonal to the frame loop. We keep the
215
+ // live `Recorder` in a ref so `stopVideoRecording` is idempotent even if
216
+ // the parent calls it twice (e.g. on SESSION_COMPLETE and again on
217
+ // unmount). In v5 a Recorder is single-use: one is created per recording
218
+ // and discarded once it finishes.
219
+ const recorderRef = useRef<Recorder | null>(null);
220
+ // Duration read off the Recorder just before finalising. v5's
221
+ // `onRecordingFinished` only carries the file path, but the upload
222
+ // pipeline reports the duration in the `liveness-verify` metadata.
223
+ const recordedDurationRef = useRef<number | undefined>(undefined);
158
224
 
159
225
  const startVideoRecording = useCallback(
160
- (opts: {
161
- onRecordingFinished: (video: VideoFile) => void;
226
+ async (opts: {
227
+ onRecordingFinished: (video: LivenessVideoFile) => void;
162
228
  onRecordingError: (err: unknown) => void;
163
- }) => {
164
- const camera = cameraRef.current;
165
- if (!camera) {
166
- throw new Error('Camera is not mounted; cannot start recording.');
229
+ }): Promise<void> => {
230
+ if (recorderRef.current) return;
231
+ const recorder = await videoOutput.createRecorder({});
232
+ recorderRef.current = recorder;
233
+ recordedDurationRef.current = undefined;
234
+ try {
235
+ await recorder.startRecording(
236
+ (filePath) => {
237
+ const duration =
238
+ recordedDurationRef.current ??
239
+ (typeof recorder.recordedDuration === 'number'
240
+ ? recorder.recordedDuration
241
+ : undefined);
242
+ recorderRef.current = null;
243
+ opts.onRecordingFinished({ path: filePath, duration });
244
+ },
245
+ (error) => {
246
+ recorderRef.current = null;
247
+ opts.onRecordingError(error);
248
+ },
249
+ );
250
+ } catch (err) {
251
+ // Startup failed, so neither callback will ever fire — release the
252
+ // ref here or every later start would short-circuit on it.
253
+ recorderRef.current = null;
254
+ throw err;
167
255
  }
168
- if (recordingRef.current) return;
169
- recordingRef.current = true;
170
- camera.startRecording({
171
- fileType: 'mp4',
172
- videoCodec: 'h264',
173
- flash: 'off',
174
- onRecordingFinished: (video) => {
175
- recordingRef.current = false;
176
- opts.onRecordingFinished(video);
177
- },
178
- onRecordingError: (err) => {
179
- recordingRef.current = false;
180
- opts.onRecordingError(err);
181
- },
182
- });
183
256
  },
184
- [],
257
+ [videoOutput],
185
258
  );
186
259
 
187
260
  const stopVideoRecording = useCallback(async (): Promise<void> => {
188
- const camera = cameraRef.current;
189
- if (!camera || !recordingRef.current) return;
190
- await camera.stopRecording();
191
- // recordingRef is cleared inside onRecordingFinished/onRecordingError to
192
- // avoid a window where a follow-up start() races with the unfinished stop.
261
+ const recorder = recorderRef.current;
262
+ if (!recorder) return;
263
+ // Read the duration BEFORE stopping: once the recording is finalised the
264
+ // counter is no longer meaningful, and `onRecordingFinished` does not
265
+ // carry it.
266
+ try {
267
+ recordedDurationRef.current =
268
+ typeof recorder.recordedDuration === 'number'
269
+ ? recorder.recordedDuration
270
+ : undefined;
271
+ } catch {
272
+ recordedDurationRef.current = undefined;
273
+ }
274
+ await recorder.stopRecording();
275
+ // recorderRef is cleared inside onRecordingFinished/onRecordingError to
276
+ // avoid a window where a follow-up start races with the unfinished stop.
193
277
  }, []);
194
278
 
195
279
  useImperativeHandle(
@@ -263,33 +347,22 @@ export const LivenessCamera = forwardRef<LivenessCameraHandle, LivenessCameraPro
263
347
  ref={cameraRef}
264
348
  style={StyleSheet.absoluteFill}
265
349
  device={device}
266
- // `format` and `fps` cap the sensor output to 720p / 30 fps so the
267
- // recorded mp4 lands in the few-MB range instead of the device
268
- // default (which on modern iPhones is 1080p–4K @ 60 fps).
269
- {...(format ? { format } : {})}
270
- fps={30}
271
- // Cap the encoder to ~2 Mbps. The default `'normal'` setting maps
272
- // to ~8 Mbps for 720p, producing a 38 MB file for a 30 s session;
273
- // ~2 Mbps is plenty for face visibility (compliance evidence) and
274
- // keeps a 30 s recording around 7-8 MB.
275
- videoBitRate={2}
276
- // Lock the recorded video orientation to the preview view's so it
277
- // is never upside-down or sideways on the back-office player.
278
- outputOrientation="preview"
279
- photo
280
- // Enable mp4/h264 recording in parallel with takePhoto(). vision-camera
281
- // v4 supports both surfaces on the same <Camera>; the recording runs
282
- // best-effort and does not affect the frame cadence sent to Iris.
283
- video
284
- audio={false}
285
- photoQualityBalance="speed"
286
- // Keep the vision-camera default (`isMirrored=true` for front cam):
287
- // overriding it to `false` causes a v4 iOS bug where the tkhd matrix
288
- // is written rotated −90° instead of +90°, leaving the recorded mp4
289
- // upside-down. The JPEG frames we send to Iris are un-mirrored
290
- // separately in `captureAndSend` via a horizontal flip with
291
- // expo-image-manipulator, so TURN_LEFT/RIGHT still maps to the
292
- // real-world yaw.
350
+ // Android: preview + video only. Photo stills on the same session
351
+ // as the recorder were the LOW_SHARPNESS / MiniFAS failure.
352
+ // iOS: photo + video; snapshot is not available.
353
+ outputs={[photoOutput, videoOutput]}
354
+ // Cap the sensor at 30 fps. Resolution and bit-rate are set on the
355
+ // video output itself (see `useVideoOutput` above).
356
+ constraints={[{ fps: 30 }]}
357
+ // Lock the recorded video orientation to the interface's so it is
358
+ // never upside-down or sideways on the back-office player. (v5's
359
+ // spelling of what v4 called `outputOrientation="preview"`.)
360
+ orientationSource="interface"
361
+ // We keep the front camera's default mirroring rather than forcing
362
+ // `isMirrored=false`: in v4 that override triggered an iOS bug where
363
+ // the tkhd matrix was written rotated −90° instead of +90°, leaving
364
+ // the mp4 upside-down. Preview snapshots are un-mirrored in
365
+ // `takeFrame` before they go to Iris (OSDKR-23).
293
366
  isActive
294
367
  />
295
368
  <OvalOverlay
@@ -356,7 +356,7 @@ const styles = StyleSheet.create({
356
356
  // so any backdrop colour would only show briefly while tiles are loading.
357
357
  },
358
358
  mapLoading: {
359
- ...StyleSheet.absoluteFillObject,
359
+ ...StyleSheet.absoluteFill,
360
360
  alignItems: 'center',
361
361
  justifyContent: 'center',
362
362
  },
@@ -49,6 +49,7 @@ import { useTheme, mixHex } from '../ui/theme';
49
49
  import { getStrings } from '../i18n';
50
50
  import { resolveCaptureModeFromStepConfig } from '../utils/stepConfig';
51
51
  import { log } from '../utils/log';
52
+ import { byteLengthOfUri, readBytesFromUri } from '../utils/jpegFromUri';
52
53
  import { DocumentCapture, type CaptureGuide } from '../camera/DocumentCapture';
53
54
  import {
54
55
  computeGuideCropRect,
@@ -170,7 +171,24 @@ function DocumentsOcrView({
170
171
  const handleCaptured = useCallback(
171
172
  async (photo: PhotoFile, side: DocumentSide, guide: CaptureGuide) => {
172
173
  try {
173
- const compressed = await compressJpeg(photo.path, guide);
174
+ // Size of the raw capture BEFORE any processing. Logged next to the
175
+ // compressed size so a 0-byte upload can be traced to the stage that
176
+ // lost it — the capture itself, the crop/compress, or the upload
177
+ // (OSDKR-22).
178
+ const sourceBytes = byteLengthOfUri(photo.filePath);
179
+ const compressed = await compressJpeg(photo.filePath, guide);
180
+ log.info('[DocumentsOCR] side processed', {
181
+ side,
182
+ sourceBytes,
183
+ compressedBytes: compressed.byteLength,
184
+ width: compressed.width,
185
+ height: compressed.height,
186
+ });
187
+ if (compressed.byteLength === 0) {
188
+ throw new Error(
189
+ `Processed ${side} image is 0 bytes (source was ${sourceBytes} bytes).`,
190
+ );
191
+ }
174
192
  if (compressed.byteLength > MAX_BYTES) {
175
193
  setBannerError(t.documents_ocr.fileTooLarge);
176
194
  // Stay on the capture phase so the user can retake immediately.
@@ -205,10 +223,18 @@ function DocumentsOcrView({
205
223
  }
206
224
 
207
225
  setBusyLabel(t.documents_ocr.uploadingFront);
208
- await uploadJpeg(front.uri, init.front_side_upload_url);
226
+ await uploadJpeg(
227
+ front.uri,
228
+ init.front_side_upload_url,
229
+ init.max_file_size_bytes,
230
+ );
209
231
 
210
232
  setBusyLabel(t.documents_ocr.uploadingBack);
211
- await uploadJpeg(back.uri, init.back_side_upload_url);
233
+ await uploadJpeg(
234
+ back.uri,
235
+ init.back_side_upload_url,
236
+ init.max_file_size_bytes,
237
+ );
212
238
 
213
239
  setBusyLabel(t.documents_ocr.verifying);
214
240
  await api.post(`/sessions/${sessionId}/documents-verify`, {});
@@ -438,7 +464,7 @@ async function compressJpeg(
438
464
  //
439
465
  // We crop strictly to the on-screen guide rectangle the user centred the
440
466
  // document in; we never inspect pixels and we never rotate based on how the
441
- // phone was held — `DocumentCapture` pins `outputOrientation="preview"` so
467
+ // phone was held — `DocumentCapture` pins `orientationSource="interface"` so
442
468
  // the capture always comes back in the orientation the user framed.
443
469
  const loadContext = ImageManipulatorModule.manipulate(source);
444
470
  const loaded = await loadContext.renderAsync();
@@ -502,7 +528,7 @@ async function compressJpeg(
502
528
  compress: COMPRESS_QUALITY,
503
529
  format: SaveFormat.JPEG,
504
530
  });
505
- const byteLength = await fetchByteLength(result.uri);
531
+ const byteLength = byteLengthOfUri(result.uri);
506
532
  return {
507
533
  uri: result.uri,
508
534
  width: result.width,
@@ -519,27 +545,143 @@ async function compressJpeg(
519
545
  }
520
546
  }
521
547
 
522
- async function uploadJpeg(uri: string, signedUrl: string): Promise<void> {
523
- const response = await fetch(uri);
524
- if (!response.ok) {
525
- throw new Error(`Could not read captured photo: HTTP ${response.status}`);
548
+ /**
549
+ * Uploads a captured JPEG to its signed URL.
550
+ *
551
+ * The bytes are read with `expo-file-system`, NOT with `fetch(uri)`. Since
552
+ * Expo SDK 57 the global `fetch` is Expo's native HTTP client, which does not
553
+ * handle the `file://` scheme and answers with an empty body rather than
554
+ * failing — so reading a capture through it uploaded a 0-byte object while
555
+ * every status code said success (OSDKR-22).
556
+ *
557
+ * Expo's `fetch` normalises any `ArrayBuffer.isView` into the request body, so
558
+ * a `Uint8Array` is a valid body here.
559
+ */
560
+ async function uploadJpeg(
561
+ uri: string,
562
+ signedUrl: string,
563
+ maxFileSizeBytes: number | undefined,
564
+ ): Promise<void> {
565
+ const bytes = await readBytesFromUri(uri);
566
+ // Never PUT an empty body: the bucket accepts it, the step reports success,
567
+ // and the failure only surfaces later as an unexplained backend rejection.
568
+ if (bytes.byteLength === 0) {
569
+ throw new Error('Captured photo read back as 0 bytes — refusing to upload it.');
570
+ }
571
+ // The CDN signs the URL with an `x-goog-content-length-range` extension
572
+ // header, and GCS rejects the PUT unless every signed header is present in
573
+ // the request — with `MalformedSecurityHeader`, not with a size error, so it
574
+ // reads like a signature problem (OSDKR-22).
575
+ //
576
+ // The value has to match what was signed byte for byte. The CDN builds it as
577
+ // `"0," + maxUploadBytes` and returns that same number as the
578
+ // `max_file_size_bytes` of `documents-init`, so the number below is the one
579
+ // that went into the signature, not a guess.
580
+ const headers: Record<string, string> = { 'Content-Type': 'image/jpeg' };
581
+ if (typeof maxFileSizeBytes === 'number') {
582
+ headers['x-goog-content-length-range'] = `0,${maxFileSizeBytes}`;
583
+ }
584
+
585
+ // Reject oversize captures here rather than letting GCS do it: past the
586
+ // signed ceiling the bucket answers with the same opaque 400.
587
+ if (typeof maxFileSizeBytes === 'number' && bytes.byteLength > maxFileSizeBytes) {
588
+ throw new Error(
589
+ `Captured image is ${bytes.byteLength} bytes, over the ${maxFileSizeBytes}-byte limit the upload URL was signed for.`,
590
+ );
591
+ }
592
+
593
+ // If the signature covers the range header but `documents-init` did not give
594
+ // us the number, the PUT cannot succeed and the reason is a contract gap, not
595
+ // a client bug. Say so before failing, so it is not diagnosed as a signature
596
+ // problem again.
597
+ const required = describeSignedUrl(signedUrl).signedHeaders ?? '';
598
+ if (
599
+ required.includes('x-goog-content-length-range') &&
600
+ typeof maxFileSizeBytes !== 'number'
601
+ ) {
602
+ log.warn(
603
+ '[DocumentsOCR] upload URL is signed over x-goog-content-length-range but ' +
604
+ 'documents-init returned no max_file_size_bytes — the PUT will be rejected ' +
605
+ 'with MalformedSecurityHeader.',
606
+ );
526
607
  }
527
- const blob = await response.blob();
608
+
609
+ log.info('[DocumentsOCR] uploading side', {
610
+ bytes: bytes.byteLength,
611
+ maxFileSizeBytes: maxFileSizeBytes ?? null,
612
+ sentHeaders: Object.keys(headers),
613
+ });
614
+ const startedAt = Date.now();
528
615
  const put = await fetch(signedUrl, {
529
616
  method: 'PUT',
530
- headers: { 'Content-Type': 'image/jpeg' },
531
- body: blob,
617
+ headers,
618
+ body: bytes,
619
+ });
620
+ // The bucket echoes back what it stored. `etag` is a checksum of the stored
621
+ // object, so a constant etag across two different captures means nothing
622
+ // reached it — the symptom that took a full manual run to notice before.
623
+ // The signed URL is never logged: it carries the V4 signature.
624
+ log.info('[DocumentsOCR] side uploaded', {
625
+ sentBytes: bytes.byteLength,
626
+ status: put.status,
627
+ etag: put.headers.get('etag'),
628
+ elapsedMs: Date.now() - startedAt,
532
629
  });
533
630
  if (!put.ok) {
534
- throw new Error(`Signed URL upload failed: HTTP ${put.status}`);
631
+ // A signed-URL rejection is never self-explanatory from the status alone:
632
+ // 400 covers a stale signature, an expired URL and a Content-Type that
633
+ // does not match what was signed. GCS puts the actual reason in an XML
634
+ // body, so read it before throwing (OSDKR-22).
635
+ let reason = '';
636
+ let body = '';
637
+ try {
638
+ body = (await put.text()).slice(0, 400);
639
+ reason = body.match(/<Code>([^<]+)<\/Code>/)?.[1] ?? '';
640
+ } catch {
641
+ /* body not readable; the status and the signed-URL shape are the signal */
642
+ }
643
+ log.warn('[DocumentsOCR] side upload rejected', {
644
+ status: put.status,
645
+ reason,
646
+ sentBytes: bytes.byteLength,
647
+ sentHeaders: Object.keys(headers),
648
+ // Describes the signed URL without ever exposing its signature. The
649
+ // decisive field is usually `signedHeaders`: it lists the headers the
650
+ // signature covers, so a mismatch with what we actually sent shows up
651
+ // here immediately.
652
+ signedUrl: describeSignedUrl(signedUrl),
653
+ body,
654
+ });
655
+ throw new Error(
656
+ `Signed URL upload failed: HTTP ${put.status}${reason ? ` (${reason})` : ''}`,
657
+ );
535
658
  }
536
659
  }
537
660
 
538
- async function fetchByteLength(uri: string): Promise<number> {
539
- const response = await fetch(uri);
540
- if (!response.ok) return 0;
541
- const blob = await response.blob();
542
- return blob.size;
661
+ /**
662
+ * Summarises a signed URL for logging — host, path and the signing parameters
663
+ * that explain a rejection — while deliberately omitting `X-Goog-Signature`.
664
+ *
665
+ * `signedHeaders` and `expires` are what actually diagnose a 400: the first
666
+ * says which headers the signature covers, the second whether the URL simply
667
+ * aged out between `documents-init` and the upload.
668
+ */
669
+ function describeSignedUrl(signedUrl: string): Record<string, string | null> {
670
+ try {
671
+ const url = new URL(signedUrl);
672
+ const q = url.searchParams;
673
+ return {
674
+ host: url.host,
675
+ path: url.pathname,
676
+ algorithm: q.get('X-Goog-Algorithm'),
677
+ date: q.get('X-Goog-Date'),
678
+ expiresIn: q.get('X-Goog-Expires'),
679
+ signedHeaders: q.get('X-Goog-SignedHeaders'),
680
+ hasSignature: q.has('X-Goog-Signature') ? 'yes' : 'no',
681
+ };
682
+ } catch {
683
+ return { parseError: 'could not parse signed URL' };
684
+ }
543
685
  }
544
686
 
545
687
  /**