@marinoscar/vault-web 0.0.0-bootstrap → 0.1.0-next.3

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 (277) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/LICENSE +21 -0
  3. package/README.md +99 -0
  4. package/dist/agent/headless/agentActivity.d.ts +53 -0
  5. package/dist/agent/headless/agentActivity.js +58 -0
  6. package/dist/agent/headless/index.d.ts +2 -0
  7. package/dist/agent/headless/index.js +3 -0
  8. package/dist/agent/headless/useAgentActivity.d.ts +9 -0
  9. package/dist/agent/headless/useAgentActivity.js +30 -0
  10. package/dist/agent/ui/components/AgentActivityTable.d.ts +25 -0
  11. package/dist/agent/ui/components/AgentActivityTable.js +114 -0
  12. package/dist/agent/ui/index.d.ts +3 -0
  13. package/dist/agent/ui/index.js +4 -0
  14. package/dist/agent/ui/pages/AgentAccessSettingsPage.d.ts +7 -0
  15. package/dist/agent/ui/pages/AgentAccessSettingsPage.js +70 -0
  16. package/dist/agent/ui/pages/AgentActivityPage.d.ts +6 -0
  17. package/dist/agent/ui/pages/AgentActivityPage.js +61 -0
  18. package/dist/backups/headless/backupContents.d.ts +69 -0
  19. package/dist/backups/headless/backupContents.js +133 -0
  20. package/dist/backups/headless/backupPassword.d.ts +34 -0
  21. package/dist/backups/headless/backupPassword.js +80 -0
  22. package/dist/backups/headless/backupSchedule.d.ts +56 -0
  23. package/dist/backups/headless/backupSchedule.js +189 -0
  24. package/dist/backups/headless/index.d.ts +4 -0
  25. package/dist/backups/headless/index.js +5 -0
  26. package/dist/backups/headless/useBackupRunHistory.d.ts +36 -0
  27. package/dist/backups/headless/useBackupRunHistory.js +83 -0
  28. package/dist/backups/ui/components/AdminBackupDownloadDialog.d.ts +20 -0
  29. package/dist/backups/ui/components/AdminBackupDownloadDialog.js +65 -0
  30. package/dist/backups/ui/components/BackupContentsGroup.d.ts +17 -0
  31. package/dist/backups/ui/components/BackupContentsGroup.js +21 -0
  32. package/dist/backups/ui/components/BackupPasswordFields.d.ts +18 -0
  33. package/dist/backups/ui/components/BackupPasswordFields.js +40 -0
  34. package/dist/backups/ui/components/BackupRunsTable.d.ts +44 -0
  35. package/dist/backups/ui/components/BackupRunsTable.js +61 -0
  36. package/dist/backups/ui/components/DataBackup.d.ts +14 -0
  37. package/dist/backups/ui/components/DataBackup.js +169 -0
  38. package/dist/backups/ui/components/ScheduledBackups.d.ts +13 -0
  39. package/dist/backups/ui/components/ScheduledBackups.js +304 -0
  40. package/dist/backups/ui/index.d.ts +8 -0
  41. package/dist/backups/ui/index.js +9 -0
  42. package/dist/backups/ui/pages/BackupSettingsPage.d.ts +8 -0
  43. package/dist/backups/ui/pages/BackupSettingsPage.js +19 -0
  44. package/dist/backups/ui/pages/MyBackupsPage.d.ts +8 -0
  45. package/dist/backups/ui/pages/MyBackupsPage.js +19 -0
  46. package/dist/brand/BrandLockup.d.ts +14 -0
  47. package/dist/brand/BrandLockup.js +13 -0
  48. package/dist/brand/assets/vault-mark.png +0 -0
  49. package/dist/brand/contrast.d.ts +8 -0
  50. package/dist/brand/contrast.js +21 -0
  51. package/dist/brand/index.d.ts +7 -0
  52. package/dist/brand/index.js +8 -0
  53. package/dist/brand/mark.d.ts +6 -0
  54. package/dist/brand/mark.js +7 -0
  55. package/dist/brand/theme.d.ts +25 -0
  56. package/dist/brand/theme.js +84 -0
  57. package/dist/brand/tokens.d.ts +52 -0
  58. package/dist/brand/tokens.js +54 -0
  59. package/dist/cards/headless/cardExpiry.d.ts +57 -0
  60. package/dist/cards/headless/cardExpiry.js +138 -0
  61. package/dist/cards/headless/cardFormat.d.ts +60 -0
  62. package/dist/cards/headless/cardFormat.js +135 -0
  63. package/dist/cards/headless/cardImage.d.ts +293 -0
  64. package/dist/cards/headless/cardImage.js +518 -0
  65. package/dist/cards/headless/index.d.ts +6 -0
  66. package/dist/cards/headless/index.js +7 -0
  67. package/dist/cards/headless/useCardImport.d.ts +137 -0
  68. package/dist/cards/headless/useCardImport.js +391 -0
  69. package/dist/cards/headless/useCardRenewal.d.ts +102 -0
  70. package/dist/cards/headless/useCardRenewal.js +305 -0
  71. package/dist/cards/headless/useCards.d.ts +80 -0
  72. package/dist/cards/headless/useCards.js +114 -0
  73. package/dist/cards/ui/components/AiEgressNotice.d.ts +13 -0
  74. package/dist/cards/ui/components/AiEgressNotice.js +18 -0
  75. package/dist/cards/ui/components/CardCaptureStep.d.ts +59 -0
  76. package/dist/cards/ui/components/CardCaptureStep.js +96 -0
  77. package/dist/cards/ui/components/CardCropAdjuster.d.ts +43 -0
  78. package/dist/cards/ui/components/CardCropAdjuster.js +215 -0
  79. package/dist/cards/ui/components/CardCropReview.d.ts +51 -0
  80. package/dist/cards/ui/components/CardCropReview.js +88 -0
  81. package/dist/cards/ui/components/CardExpiryBadge.d.ts +8 -0
  82. package/dist/cards/ui/components/CardExpiryBadge.js +43 -0
  83. package/dist/cards/ui/components/CardFieldDiff.d.ts +37 -0
  84. package/dist/cards/ui/components/CardFieldDiff.js +66 -0
  85. package/dist/cards/ui/components/CardFlowStepper.d.ts +24 -0
  86. package/dist/cards/ui/components/CardFlowStepper.js +23 -0
  87. package/dist/cards/ui/components/CardReviewForm.d.ts +44 -0
  88. package/dist/cards/ui/components/CardReviewForm.js +102 -0
  89. package/dist/cards/ui/components/CardScanModelSection.d.ts +23 -0
  90. package/dist/cards/ui/components/CardScanModelSection.js +81 -0
  91. package/dist/cards/ui/components/CardTile.d.ts +40 -0
  92. package/dist/cards/ui/components/CardTile.js +94 -0
  93. package/dist/cards/ui/index.d.ts +15 -0
  94. package/dist/cards/ui/index.js +16 -0
  95. package/dist/cards/ui/pages/AiSettingsPage.d.ts +12 -0
  96. package/dist/cards/ui/pages/AiSettingsPage.js +24 -0
  97. package/dist/cards/ui/pages/CardsPage.d.ts +26 -0
  98. package/dist/cards/ui/pages/CardsPage.js +160 -0
  99. package/dist/cards/ui/pages/ImportCardPage.d.ts +24 -0
  100. package/dist/cards/ui/pages/ImportCardPage.js +343 -0
  101. package/dist/cards/ui/pages/RenewCardPage.d.ts +35 -0
  102. package/dist/cards/ui/pages/RenewCardPage.js +350 -0
  103. package/dist/core/headless/api.d.ts +272 -0
  104. package/dist/core/headless/api.js +425 -0
  105. package/dist/core/headless/cardScanAvailability.d.ts +20 -0
  106. package/dist/core/headless/cardScanAvailability.js +27 -0
  107. package/dist/core/headless/clipboard.d.ts +60 -0
  108. package/dist/core/headless/clipboard.js +101 -0
  109. package/dist/core/headless/http.d.ts +41 -0
  110. package/dist/core/headless/http.js +50 -0
  111. package/dist/core/headless/index.d.ts +12 -0
  112. package/dist/core/headless/index.js +13 -0
  113. package/dist/core/headless/relativeTime.d.ts +7 -0
  114. package/dist/core/headless/relativeTime.js +28 -0
  115. package/dist/core/headless/saveBlob.d.ts +6 -0
  116. package/dist/core/headless/saveBlob.js +21 -0
  117. package/dist/core/headless/types.d.ts +441 -0
  118. package/dist/core/headless/types.js +49 -0
  119. package/dist/core/headless/useAiStatus.d.ts +41 -0
  120. package/dist/core/headless/useAiStatus.js +42 -0
  121. package/dist/core/headless/useCopyToClipboard.d.ts +20 -0
  122. package/dist/core/headless/useCopyToClipboard.js +52 -0
  123. package/dist/core/headless/useDashboardResource.d.ts +22 -0
  124. package/dist/core/headless/useDashboardResource.js +52 -0
  125. package/dist/core/headless/useSystemSettings.d.ts +17 -0
  126. package/dist/core/headless/useSystemSettings.js +106 -0
  127. package/dist/core/headless/useUserSettings.d.ts +13 -0
  128. package/dist/core/headless/useUserSettings.js +103 -0
  129. package/dist/core/ui/ErrorBoundary.d.ts +15 -0
  130. package/dist/core/ui/ErrorBoundary.js +27 -0
  131. package/dist/core/ui/LoadingSpinner.d.ts +6 -0
  132. package/dist/core/ui/LoadingSpinner.js +14 -0
  133. package/dist/core/ui/SettingsPageFrame.d.ts +19 -0
  134. package/dist/core/ui/SettingsPageFrame.js +12 -0
  135. package/dist/core/ui/StorageSettingsLink.d.ts +19 -0
  136. package/dist/core/ui/StorageSettingsLink.js +26 -0
  137. package/dist/core/ui/index.d.ts +4 -0
  138. package/dist/core/ui/index.js +5 -0
  139. package/dist/home/headless/homeLinks.d.ts +24 -0
  140. package/dist/home/headless/homeLinks.js +24 -0
  141. package/dist/home/headless/index.d.ts +1 -0
  142. package/dist/home/headless/index.js +2 -0
  143. package/dist/home/ui/components/BackupStatusPanel.d.ts +28 -0
  144. package/dist/home/ui/components/BackupStatusPanel.js +99 -0
  145. package/dist/home/ui/components/DashboardPanel.d.ts +33 -0
  146. package/dist/home/ui/components/DashboardPanel.js +21 -0
  147. package/dist/home/ui/components/ExpiringCardsPanel.d.ts +31 -0
  148. package/dist/home/ui/components/ExpiringCardsPanel.js +35 -0
  149. package/dist/home/ui/components/FirstRunPanel.d.ts +7 -0
  150. package/dist/home/ui/components/FirstRunPanel.js +21 -0
  151. package/dist/home/ui/components/QuickActions.d.ts +14 -0
  152. package/dist/home/ui/components/QuickActions.js +40 -0
  153. package/dist/home/ui/components/RecentSecretsPanel.d.ts +19 -0
  154. package/dist/home/ui/components/RecentSecretsPanel.js +20 -0
  155. package/dist/home/ui/components/StatsRow.d.ts +19 -0
  156. package/dist/home/ui/components/StatsRow.js +46 -0
  157. package/dist/home/ui/components/WelcomeHeader.d.ts +11 -0
  158. package/dist/home/ui/components/WelcomeHeader.js +15 -0
  159. package/dist/home/ui/index.d.ts +9 -0
  160. package/dist/home/ui/index.js +10 -0
  161. package/dist/home/ui/pages/HomePage.d.ts +14 -0
  162. package/dist/home/ui/pages/HomePage.js +121 -0
  163. package/dist/index.d.ts +5 -0
  164. package/dist/index.js +5 -0
  165. package/dist/media/headless/index.d.ts +2 -0
  166. package/dist/media/headless/index.js +3 -0
  167. package/dist/media/headless/useMediaFiles.d.ts +20 -0
  168. package/dist/media/headless/useMediaFiles.js +82 -0
  169. package/dist/media/headless/useMediaFolders.d.ts +22 -0
  170. package/dist/media/headless/useMediaFolders.js +81 -0
  171. package/dist/media/ui/components/FolderList.d.ts +19 -0
  172. package/dist/media/ui/components/FolderList.js +36 -0
  173. package/dist/media/ui/components/MediaList.d.ts +20 -0
  174. package/dist/media/ui/components/MediaList.js +55 -0
  175. package/dist/media/ui/components/MediaPlayer.d.ts +7 -0
  176. package/dist/media/ui/components/MediaPlayer.js +361 -0
  177. package/dist/media/ui/index.d.ts +10 -0
  178. package/dist/media/ui/index.js +11 -0
  179. package/dist/media/ui/pages/CreateFolderPage.d.ts +1 -0
  180. package/dist/media/ui/pages/CreateFolderPage.js +39 -0
  181. package/dist/media/ui/pages/EditFolderPage.d.ts +1 -0
  182. package/dist/media/ui/pages/EditFolderPage.js +59 -0
  183. package/dist/media/ui/pages/MediaFolderPage.d.ts +1 -0
  184. package/dist/media/ui/pages/MediaFolderPage.js +68 -0
  185. package/dist/media/ui/pages/MediaFoldersPage.d.ts +1 -0
  186. package/dist/media/ui/pages/MediaFoldersPage.js +58 -0
  187. package/dist/media/ui/pages/MediaPlayerPage.d.ts +1 -0
  188. package/dist/media/ui/pages/MediaPlayerPage.js +76 -0
  189. package/dist/media/ui/pages/MediaUploadPage.d.ts +1 -0
  190. package/dist/media/ui/pages/MediaUploadPage.js +88 -0
  191. package/dist/media/ui/pages/RenameMediaFilePage.d.ts +1 -0
  192. package/dist/media/ui/pages/RenameMediaFilePage.js +63 -0
  193. package/dist/navigation/destinations.d.ts +50 -0
  194. package/dist/navigation/destinations.js +109 -0
  195. package/dist/navigation/index.d.ts +1 -0
  196. package/dist/navigation/index.js +4 -0
  197. package/dist/secrets/headless/fieldOptionsValidation.d.ts +45 -0
  198. package/dist/secrets/headless/fieldOptionsValidation.js +79 -0
  199. package/dist/secrets/headless/index.d.ts +6 -0
  200. package/dist/secrets/headless/index.js +7 -0
  201. package/dist/secrets/headless/secretFields.d.ts +86 -0
  202. package/dist/secrets/headless/secretFields.js +190 -0
  203. package/dist/secrets/headless/useSecretDetail.d.ts +33 -0
  204. package/dist/secrets/headless/useSecretDetail.js +87 -0
  205. package/dist/secrets/headless/useSecretTypes.d.ts +16 -0
  206. package/dist/secrets/headless/useSecretTypes.js +62 -0
  207. package/dist/secrets/headless/useSecrets.d.ts +24 -0
  208. package/dist/secrets/headless/useSecrets.js +59 -0
  209. package/dist/secrets/headless/useTotpCode.d.ts +24 -0
  210. package/dist/secrets/headless/useTotpCode.js +116 -0
  211. package/dist/secrets/ui/components/CardImages.d.ts +31 -0
  212. package/dist/secrets/ui/components/CardImages.js +208 -0
  213. package/dist/secrets/ui/components/DynamicSecretFields.d.ts +10 -0
  214. package/dist/secrets/ui/components/DynamicSecretFields.js +90 -0
  215. package/dist/secrets/ui/components/FieldDefinitionBuilder.d.ts +13 -0
  216. package/dist/secrets/ui/components/FieldDefinitionBuilder.js +114 -0
  217. package/dist/secrets/ui/components/FieldOptionsEditor.d.ts +15 -0
  218. package/dist/secrets/ui/components/FieldOptionsEditor.js +45 -0
  219. package/dist/secrets/ui/components/SecretAttachments.d.ts +15 -0
  220. package/dist/secrets/ui/components/SecretAttachments.js +106 -0
  221. package/dist/secrets/ui/components/SecretForm.d.ts +34 -0
  222. package/dist/secrets/ui/components/SecretForm.js +83 -0
  223. package/dist/secrets/ui/components/SecretFormDialog.d.ts +15 -0
  224. package/dist/secrets/ui/components/SecretFormDialog.js +95 -0
  225. package/dist/secrets/ui/components/SecretTypeFormDialog.d.ts +15 -0
  226. package/dist/secrets/ui/components/SecretTypeFormDialog.js +92 -0
  227. package/dist/secrets/ui/components/SecretTypeIcon.d.ts +8 -0
  228. package/dist/secrets/ui/components/SecretTypeIcon.js +16 -0
  229. package/dist/secrets/ui/components/SecretTypesList.d.ts +10 -0
  230. package/dist/secrets/ui/components/SecretTypesList.js +13 -0
  231. package/dist/secrets/ui/components/SecretValueField.d.ts +20 -0
  232. package/dist/secrets/ui/components/SecretValueField.js +52 -0
  233. package/dist/secrets/ui/components/SecretVersionDrawer.d.ts +22 -0
  234. package/dist/secrets/ui/components/SecretVersionDrawer.js +131 -0
  235. package/dist/secrets/ui/components/SecretsTable.d.ts +49 -0
  236. package/dist/secrets/ui/components/SecretsTable.js +174 -0
  237. package/dist/secrets/ui/components/TotpCodeCard.d.ts +8 -0
  238. package/dist/secrets/ui/components/TotpCodeCard.js +34 -0
  239. package/dist/secrets/ui/index.d.ts +20 -0
  240. package/dist/secrets/ui/index.js +21 -0
  241. package/dist/secrets/ui/pages/CreateSecretPage.d.ts +2 -0
  242. package/dist/secrets/ui/pages/CreateSecretPage.js +25 -0
  243. package/dist/secrets/ui/pages/CreateSecretTypePage.d.ts +1 -0
  244. package/dist/secrets/ui/pages/CreateSecretTypePage.js +62 -0
  245. package/dist/secrets/ui/pages/EditSecretPage.d.ts +5 -0
  246. package/dist/secrets/ui/pages/EditSecretPage.js +55 -0
  247. package/dist/secrets/ui/pages/EditSecretTypePage.d.ts +1 -0
  248. package/dist/secrets/ui/pages/EditSecretTypePage.js +88 -0
  249. package/dist/secrets/ui/pages/SecretDetailPage.d.ts +7 -0
  250. package/dist/secrets/ui/pages/SecretDetailPage.js +182 -0
  251. package/dist/secrets/ui/pages/SecretTypesPage.d.ts +1 -0
  252. package/dist/secrets/ui/pages/SecretTypesPage.js +23 -0
  253. package/dist/secrets/ui/pages/SecretsPage.d.ts +6 -0
  254. package/dist/secrets/ui/pages/SecretsPage.js +179 -0
  255. package/dist/settings/ui/components/FeatureFlagsList.d.ts +7 -0
  256. package/dist/settings/ui/components/FeatureFlagsList.js +46 -0
  257. package/dist/settings/ui/components/ImageUpload.d.ts +6 -0
  258. package/dist/settings/ui/components/ImageUpload.js +61 -0
  259. package/dist/settings/ui/components/ProfileSettings.d.ts +11 -0
  260. package/dist/settings/ui/components/ProfileSettings.js +55 -0
  261. package/dist/settings/ui/components/ThemeSettings.d.ts +7 -0
  262. package/dist/settings/ui/components/ThemeSettings.js +24 -0
  263. package/dist/settings/ui/components/UISettings.d.ts +9 -0
  264. package/dist/settings/ui/components/UISettings.js +25 -0
  265. package/dist/settings/ui/components/UserProfileCard.d.ts +1 -0
  266. package/dist/settings/ui/components/UserProfileCard.js +39 -0
  267. package/dist/settings/ui/components/UserSettingsSection.d.ts +23 -0
  268. package/dist/settings/ui/components/UserSettingsSection.js +29 -0
  269. package/dist/settings/ui/index.d.ts +10 -0
  270. package/dist/settings/ui/index.js +11 -0
  271. package/dist/settings/ui/pages/AppearanceSettingsPage.d.ts +6 -0
  272. package/dist/settings/ui/pages/AppearanceSettingsPage.js +11 -0
  273. package/dist/settings/ui/pages/GeneralSettingsPage.d.ts +9 -0
  274. package/dist/settings/ui/pages/GeneralSettingsPage.js +41 -0
  275. package/dist/settings/ui/pages/ProfileSettingsPage.d.ts +6 -0
  276. package/dist/settings/ui/pages/ProfileSettingsPage.js +11 -0
  277. package/package.json +146 -1
@@ -0,0 +1,518 @@
1
+ // =============================================================================
2
+ // Card image preparation & cropping
3
+ // =============================================================================
4
+ // Two images exist per card side, serving different masters:
5
+ //
6
+ // * The EXTRACTION image (`prepareCardPhoto`): the FULL photo, downscaled if
7
+ // very large but never cropped or rotated. It is sent to the extraction
8
+ // endpoint so the model can locate the card and return a bounding box —
9
+ // so the whole camera frame DOES leave the device, to the AI provider,
10
+ // but it is never uploaded to storage.
11
+ // * The ATTACHMENT image (`cropImageFileToCard` / `cropImageFileToBox`): the
12
+ // card rectangle cropped out of the photo — from the AI's returned box, or
13
+ // from the user's manual adjustment — which is the only version stored
14
+ // with the secret.
15
+ //
16
+ // Everything above the "Canvas shim" divider is pure arithmetic and is unit
17
+ // tested. Everything below it touches `document`/`Image`/`canvas` and is NOT
18
+ // tested: jsdom implements neither `HTMLCanvasElement.prototype.toBlob` nor
19
+ // `toDataURL`, so a test of the encode step would only ever assert that jsdom
20
+ // throws. The split is deliberate — keep new logic above the divider.
21
+ /**
22
+ * ISO/IEC 7810 ID-1, the physical format every payment card uses:
23
+ * 85.60 mm x 53.98 mm, i.e. ~1.586:1.
24
+ *
25
+ * Locking the crop to this ratio is what lets the user frame a shot roughly and
26
+ * still hand the model a rectangle whose proportions match a real card.
27
+ */
28
+ export const CARD_ASPECT_RATIO = 85.6 / 53.98;
29
+ /**
30
+ * Longest edge of the encoded image.
31
+ *
32
+ * Generous on purpose. An earlier 1400px cap assumed pixels past that point
33
+ * bought nothing, which proved false in practice: faint engraving (metal
34
+ * cards) photographed without filling the frame came out too small to read
35
+ * after crop + downscale. The provider downsizes internally anyway, so
36
+ * sending more pixels just lets IT decide what to keep — the only real cost
37
+ * is upload size, which the quality ladder below still bounds.
38
+ */
39
+ export const CARD_IMAGE_MAX_LONG_EDGE = 2048;
40
+ /** Starting JPEG quality. The ladder below drops from here only if it must. */
41
+ export const CARD_IMAGE_JPEG_QUALITY = 0.9;
42
+ /** Upper bound of the user-adjustable crop zoom (1 = the auto-fit rect). */
43
+ export const CARD_IMAGE_MAX_ZOOM = 4;
44
+ export const CARD_IMAGE_MIME_TYPE = 'image/jpeg';
45
+ /**
46
+ * Largest data URL the API accepts, mirroring `MAX_IMAGE_DATA_URL_LENGTH` in
47
+ * `apps/api/src/ai/ai.constants.ts`. Measured in characters, not bytes, because
48
+ * that is what the server-side `.max()` checks.
49
+ */
50
+ export const MAX_IMAGE_DATA_URL_LENGTH = 6_000_000;
51
+ /**
52
+ * Longest edge of the FULL photo prepared for extraction.
53
+ *
54
+ * Higher than {@link CARD_IMAGE_MAX_LONG_EDGE} because the card typically
55
+ * occupies only part of the frame: after the model's box is cropped out, the
56
+ * card itself lands at a fraction of this. The photo is downscaled only when
57
+ * it exceeds this — never cropped, never rotated, aspect untouched — because
58
+ * the returned box is expressed in fractions of the image exactly as sent.
59
+ */
60
+ export const CARD_PHOTO_MAX_LONG_EDGE = 3072;
61
+ /**
62
+ * Margin added around an AI-returned card box before cropping, as a fraction
63
+ * of the box's longer edge. A sliver of context absorbs a slightly-tight box
64
+ * without visibly shrinking the card in the stored attachment.
65
+ */
66
+ export const CROP_BOX_MARGIN_FRACTION = 0.04;
67
+ /**
68
+ * Quality steps tried in order until the encoded data URL fits the cap.
69
+ *
70
+ * Re-encoding at lower quality is preferred over shrinking further: a
71
+ * card number survives JPEG artefacts far better than it survives losing
72
+ * pixels.
73
+ */
74
+ const QUALITY_LADDER = [CARD_IMAGE_JPEG_QUALITY, 0.8, 0.7, 0.55, 0.4];
75
+ /**
76
+ * Quality steps for the FULL extraction photo. Starts higher than the crop
77
+ * ladder — the card's text is small relative to a full frame, so artefacts
78
+ * cost proportionally more — and stops higher, because a photo that needs
79
+ * quality 0.4 to fit the cap would be unreadable at card scale anyway.
80
+ */
81
+ const PHOTO_QUALITY_LADDER = [0.92, 0.85, 0.75, 0.6];
82
+ /** Clamp `value` into `[min, max]`. Non-finite values clamp to `min`. */
83
+ export function clamp(value, min, max) {
84
+ if (!Number.isFinite(value))
85
+ return min;
86
+ return Math.min(max, Math.max(min, value));
87
+ }
88
+ /** Normalize any number (or undefined) of quarter-turns into 0..3. */
89
+ export function normalizeQuarterTurns(turns) {
90
+ if (turns === undefined || !Number.isFinite(turns))
91
+ return 0;
92
+ return ((Math.round(turns) % 4) + 4) % 4;
93
+ }
94
+ /**
95
+ * The source frame's dimensions AFTER rotation. An odd number of quarter-turns
96
+ * swaps width and height; the crop rect is always computed against these
97
+ * effective dimensions, never the raw ones.
98
+ */
99
+ export function effectiveSourceSize(sourceWidth, sourceHeight, quarterTurns) {
100
+ assertPositiveDimensions(sourceWidth, sourceHeight);
101
+ const odd = normalizeQuarterTurns(quarterTurns) % 2 === 1;
102
+ return odd
103
+ ? { width: sourceHeight, height: sourceWidth }
104
+ : { width: sourceWidth, height: sourceHeight };
105
+ }
106
+ function assertPositiveDimensions(width, height) {
107
+ if (!Number.isFinite(width) ||
108
+ !Number.isFinite(height) ||
109
+ width <= 0 ||
110
+ height <= 0) {
111
+ throw new RangeError(`Image dimensions must be positive finite numbers; received ${width}x${height}`);
112
+ }
113
+ }
114
+ /**
115
+ * The largest rectangle of `aspectRatio` that fits inside the source frame,
116
+ * centred.
117
+ *
118
+ * This is the STARTING point, not the final word: it is what the user sees at
119
+ * zoom 1 before adjusting. The centred maximal rect is right often enough to
120
+ * be a good default, but a card that does not fill the frame (or arrives
121
+ * rotated) is fixed by the user via {@link computeAdjustedCropRect} rather
122
+ * than by retaking the shot.
123
+ *
124
+ * Results are integers because they index pixels. Every value is clamped into
125
+ * the source frame so a rounding step can never produce a rect that hangs off
126
+ * the edge, and never a zero-width rect for a source only a few pixels across.
127
+ */
128
+ export function computeCardCropRect(sourceWidth, sourceHeight, aspectRatio = CARD_ASPECT_RATIO) {
129
+ assertPositiveDimensions(sourceWidth, sourceHeight);
130
+ if (!Number.isFinite(aspectRatio) || aspectRatio <= 0) {
131
+ throw new RangeError(`Aspect ratio must be positive; received ${aspectRatio}`);
132
+ }
133
+ // Source wider than a card -> the card's height is the binding constraint,
134
+ // and we trim the sides. Otherwise the width binds and we trim top/bottom.
135
+ const sourceIsWider = sourceWidth / sourceHeight > aspectRatio;
136
+ const exactWidth = sourceIsWider ? sourceHeight * aspectRatio : sourceWidth;
137
+ const exactHeight = sourceIsWider ? sourceHeight : sourceWidth / aspectRatio;
138
+ const width = Math.max(1, Math.min(sourceWidth, Math.round(exactWidth)));
139
+ const height = Math.max(1, Math.min(sourceHeight, Math.round(exactHeight)));
140
+ return {
141
+ x: Math.max(0, Math.round((sourceWidth - width) / 2)),
142
+ y: Math.max(0, Math.round((sourceHeight - height) / 2)),
143
+ width,
144
+ height,
145
+ };
146
+ }
147
+ /**
148
+ * How far the crop rect can move from center, per axis, in effective source
149
+ * pixels, at a given zoom. Zero on an axis the crop already fills.
150
+ *
151
+ * The UI uses this to clamp the STORED pan as the user drags or zooms out, so
152
+ * pan offsets never silently accumulate past the edge of the frame.
153
+ */
154
+ export function computeMaxPan(sourceWidth, sourceHeight, zoom, aspectRatio = CARD_ASPECT_RATIO) {
155
+ const base = computeCardCropRect(sourceWidth, sourceHeight, aspectRatio);
156
+ const safeZoom = clamp(zoom, 1, CARD_IMAGE_MAX_ZOOM);
157
+ const width = Math.max(1, Math.round(base.width / safeZoom));
158
+ const height = Math.max(1, Math.round(base.height / safeZoom));
159
+ return {
160
+ x: Math.max(0, (sourceWidth - width) / 2),
161
+ y: Math.max(0, (sourceHeight - height) / 2),
162
+ };
163
+ }
164
+ /**
165
+ * The user-adjusted crop rect: the auto-fit rect of
166
+ * {@link computeCardCropRect}, shrunk by `zoom` and moved by `(panX, panY)`
167
+ * from center.
168
+ *
169
+ * `zoom` is clamped into `[1, CARD_IMAGE_MAX_ZOOM]` and the rect is clamped so
170
+ * it never leaves the source frame, whatever pan is passed in. With
171
+ * `zoom = 1, panX = 0, panY = 0` this returns exactly the auto-fit rect.
172
+ *
173
+ * NOTE ON ROTATION: rotation is applied at draw time, not here. Callers
174
+ * cropping a rotated source must pass the EFFECTIVE dimensions (see
175
+ * {@link effectiveSourceSize}) — for odd quarter-turns width and height swap.
176
+ */
177
+ export function computeAdjustedCropRect(sourceWidth, sourceHeight, zoom, panX, panY, aspectRatio = CARD_ASPECT_RATIO) {
178
+ const base = computeCardCropRect(sourceWidth, sourceHeight, aspectRatio);
179
+ const safeZoom = clamp(zoom, 1, CARD_IMAGE_MAX_ZOOM);
180
+ const width = Math.max(1, Math.round(base.width / safeZoom));
181
+ const height = Math.max(1, Math.round(base.height / safeZoom));
182
+ const offsetX = Number.isFinite(panX) ? panX : 0;
183
+ const offsetY = Number.isFinite(panY) ? panY : 0;
184
+ return {
185
+ x: clamp(Math.round((sourceWidth - width) / 2 + offsetX), 0, sourceWidth - width),
186
+ y: clamp(Math.round((sourceHeight - height) / 2 + offsetY), 0, sourceHeight - height),
187
+ width,
188
+ height,
189
+ };
190
+ }
191
+ /**
192
+ * Rotate a fractional box from as-sent (raw) coordinates into the EFFECTIVE
193
+ * frame — the raw frame after `quarterTurns` clockwise quarter-turns, the
194
+ * coordinate space every crop rect in this module lives in.
195
+ *
196
+ * Derived from the same point mapping `drawCardCrop` composes: for one
197
+ * clockwise turn a raw fractional point `(u, v)` lands at `(1 - v, u)`, and
198
+ * a box maps corner-wise from there.
199
+ */
200
+ function rotateFractionalBox(x, y, width, height, quarterTurns) {
201
+ switch (normalizeQuarterTurns(quarterTurns)) {
202
+ case 1:
203
+ return { x: 1 - y - height, y: x, width: height, height: width };
204
+ case 2:
205
+ return { x: 1 - x - width, y: 1 - y - height, width, height };
206
+ case 3:
207
+ return { x: y, y: 1 - x - width, width: height, height: width };
208
+ default:
209
+ return { x, y, width, height };
210
+ }
211
+ }
212
+ /**
213
+ * Convert an AI-returned fractional box into a pixel crop rect ready for
214
+ * {@link drawCardCrop}: fractions -> pixels, a small margin added, snapped to
215
+ * the card aspect ratio around the box centre, clamped inside the image.
216
+ *
217
+ * `imageWidth`/`imageHeight` are the RAW dimensions of the image the crop is
218
+ * rendered from. The returned rect is in EFFECTIVE coordinates — the frame
219
+ * after the box's `quarterTurns` have been applied (see
220
+ * {@link effectiveSourceSize}) — and must be paired with those same
221
+ * `quarterTurns` at draw time.
222
+ *
223
+ * The aspect snap only ever GROWS the box (the short axis is extended), so a
224
+ * tight box never cuts into the card; if growth would overflow the frame the
225
+ * rect is scaled down uniformly, preserving the aspect, and shifted inside.
226
+ *
227
+ * Throws `RangeError` for a degenerate box (no area inside the image), which
228
+ * callers treat as "no usable box" and fall back to the auto-fit crop.
229
+ */
230
+ export function cropRectFromBox(imageWidth, imageHeight, box, aspectRatio = CARD_ASPECT_RATIO, marginFraction = CROP_BOX_MARGIN_FRACTION) {
231
+ assertPositiveDimensions(imageWidth, imageHeight);
232
+ if (!Number.isFinite(aspectRatio) || aspectRatio <= 0) {
233
+ throw new RangeError(`Aspect ratio must be positive; received ${aspectRatio}`);
234
+ }
235
+ const turns = normalizeQuarterTurns(box.quarterTurns);
236
+ // Sanitize the fractions: clamp into the unit square. A model box that pokes
237
+ // slightly outside the frame is trimmed rather than rejected.
238
+ const bx = clamp(box.x, 0, 1);
239
+ const by = clamp(box.y, 0, 1);
240
+ const bw = clamp(box.width, 0, 1 - bx);
241
+ const bh = clamp(box.height, 0, 1 - by);
242
+ if (bw <= 0 || bh <= 0) {
243
+ throw new RangeError('Crop box has no area inside the image');
244
+ }
245
+ const rotated = rotateFractionalBox(bx, by, bw, bh, turns);
246
+ const effective = effectiveSourceSize(imageWidth, imageHeight, turns);
247
+ // Fractions -> pixels, then pad every side by the margin.
248
+ let width = rotated.width * effective.width;
249
+ let height = rotated.height * effective.height;
250
+ const margin = clamp(marginFraction, 0, 0.5) * Math.max(width, height);
251
+ const centerX = rotated.x * effective.width + width / 2;
252
+ const centerY = rotated.y * effective.height + height / 2;
253
+ width += 2 * margin;
254
+ height += 2 * margin;
255
+ // Snap to the card aspect around the centre, growing the short axis only.
256
+ if (width / height > aspectRatio) {
257
+ height = width / aspectRatio;
258
+ }
259
+ else {
260
+ width = height * aspectRatio;
261
+ }
262
+ // Too big for the frame on either axis -> scale down uniformly.
263
+ const fit = Math.min(1, effective.width / width, effective.height / height);
264
+ width *= fit;
265
+ height *= fit;
266
+ const outWidth = Math.max(1, Math.min(Math.round(width), effective.width));
267
+ const outHeight = Math.max(1, Math.min(Math.round(height), effective.height));
268
+ return {
269
+ x: clamp(Math.round(centerX - width / 2), 0, effective.width - outWidth),
270
+ y: clamp(Math.round(centerY - height / 2), 0, effective.height - outHeight),
271
+ width: outWidth,
272
+ height: outHeight,
273
+ };
274
+ }
275
+ /**
276
+ * Express an explicit crop rect (EFFECTIVE coordinates) in the adjuster's
277
+ * zoom/pan/turns model, so {@link computeAdjustedCropRect} reproduces it (up
278
+ * to rounding).
279
+ *
280
+ * `zoom` is the ratio of the auto-fit rect to this one, clamped into the
281
+ * adjuster's `[1, CARD_IMAGE_MAX_ZOOM]` range — a rect outside that range is
282
+ * approximated by the nearest representable framing. Pan is the offset of the
283
+ * rect's centre from the frame's centre.
284
+ */
285
+ export function adjustmentsFromCropRect(sourceWidth, sourceHeight, crop, quarterTurns, aspectRatio = CARD_ASPECT_RATIO) {
286
+ const turns = normalizeQuarterTurns(quarterTurns);
287
+ const effective = effectiveSourceSize(sourceWidth, sourceHeight, turns);
288
+ const base = computeCardCropRect(effective.width, effective.height, aspectRatio);
289
+ return {
290
+ zoom: clamp(base.width / Math.max(1, crop.width), 1, CARD_IMAGE_MAX_ZOOM),
291
+ panX: crop.x + crop.width / 2 - effective.width / 2,
292
+ panY: crop.y + crop.height / 2 - effective.height / 2,
293
+ quarterTurns: turns,
294
+ };
295
+ }
296
+ /**
297
+ * Seed the adjuster from an AI-returned box: {@link cropRectFromBox} then
298
+ * {@link adjustmentsFromCropRect}, so the adjuster opens showing (as near as
299
+ * its model allows) exactly the crop the box produced.
300
+ */
301
+ export function adjustmentsFromCropBox(sourceWidth, sourceHeight, box, aspectRatio = CARD_ASPECT_RATIO) {
302
+ const crop = cropRectFromBox(sourceWidth, sourceHeight, box, aspectRatio);
303
+ return adjustmentsFromCropRect(sourceWidth, sourceHeight, crop, box.quarterTurns, aspectRatio);
304
+ }
305
+ /**
306
+ * Downscale the crop so its longest edge is at most `maxLongEdge`.
307
+ *
308
+ * Never upscales: a low-resolution capture stays low-resolution rather than
309
+ * being inflated into a bigger file that carries no extra detail.
310
+ */
311
+ export function computeOutputSize(cropWidth, cropHeight, maxLongEdge = CARD_IMAGE_MAX_LONG_EDGE) {
312
+ assertPositiveDimensions(cropWidth, cropHeight);
313
+ if (!Number.isFinite(maxLongEdge) || maxLongEdge <= 0) {
314
+ throw new RangeError(`Max long edge must be positive; received ${maxLongEdge}`);
315
+ }
316
+ const longEdge = Math.max(cropWidth, cropHeight);
317
+ const scale = Math.min(1, maxLongEdge / longEdge);
318
+ return {
319
+ width: Math.max(1, Math.round(cropWidth * scale)),
320
+ height: Math.max(1, Math.round(cropHeight * scale)),
321
+ scale,
322
+ };
323
+ }
324
+ /**
325
+ * Crop rect plus the size it will be encoded at.
326
+ *
327
+ * With no adjustments in `options` this plans exactly the auto-fit centred
328
+ * crop it always has. With adjustments, the crop rect is computed against the
329
+ * ROTATED (effective) frame; the returned `quarterTurns` tells the renderer
330
+ * which rotation to apply at draw time so the rect lands where the user aimed.
331
+ */
332
+ export function planCardCrop(sourceWidth, sourceHeight, options = {}) {
333
+ const quarterTurns = normalizeQuarterTurns(options.quarterTurns);
334
+ const effective = effectiveSourceSize(sourceWidth, sourceHeight, quarterTurns);
335
+ const crop = computeAdjustedCropRect(effective.width, effective.height, options.zoom ?? 1, options.panX ?? 0, options.panY ?? 0, options.aspectRatio ?? CARD_ASPECT_RATIO);
336
+ const output = computeOutputSize(crop.width, crop.height, options.maxLongEdge ?? CARD_IMAGE_MAX_LONG_EDGE);
337
+ return { crop, output, quarterTurns };
338
+ }
339
+ /**
340
+ * Decode a base64 data URL into a Blob.
341
+ *
342
+ * Used instead of `canvas.toBlob` so the canvas is encoded exactly once: the
343
+ * data URL measured against the size cap and the file uploaded to storage are
344
+ * guaranteed to be the same bytes, not two encodes that merely look alike.
345
+ */
346
+ export function dataUrlToBlob(dataUrl) {
347
+ const match = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrl);
348
+ if (!match) {
349
+ throw new Error('Expected a base64 data URL');
350
+ }
351
+ const [, mimeType, base64] = match;
352
+ const binary = atob(base64);
353
+ const bytes = new Uint8Array(binary.length);
354
+ for (let i = 0; i < binary.length; i++) {
355
+ bytes[i] = binary.charCodeAt(i);
356
+ }
357
+ return new Blob([bytes], { type: mimeType });
358
+ }
359
+ async function loadImageElement(file) {
360
+ const url = URL.createObjectURL(file);
361
+ try {
362
+ return await new Promise((resolve, reject) => {
363
+ const image = new Image();
364
+ image.onload = () => resolve(image);
365
+ image.onerror = () => reject(new Error('That file could not be read as an image.'));
366
+ image.src = url;
367
+ });
368
+ }
369
+ finally {
370
+ URL.revokeObjectURL(url);
371
+ }
372
+ }
373
+ /**
374
+ * Draw a planned card crop onto a destination rectangle, applying the plan's
375
+ * rotation.
376
+ *
377
+ * Shared by the final encode in {@link cropImageFileToCard} and the live
378
+ * preview in the adjust UI, so what the user sees while adjusting is drawn by
379
+ * the same code as what gets encoded. `destWidth`/`destHeight` need not match
380
+ * `plan.output` — the preview draws at screen resolution.
381
+ *
382
+ * The unrotated path is the exact `drawImage` source-rect call this module has
383
+ * always made. The rotated paths compose translate/rotate so that a point
384
+ * `(u, v)` of the raw source lands where the effective (rotated) frame puts
385
+ * it, then shift/scale the crop rect onto the destination.
386
+ */
387
+ export function drawCardCrop(context, image, sourceWidth, sourceHeight, plan, destWidth, destHeight) {
388
+ const { crop } = plan;
389
+ const turns = normalizeQuarterTurns(plan.quarterTurns);
390
+ if (turns === 0) {
391
+ context.drawImage(image, crop.x, crop.y, crop.width, crop.height, 0, 0, destWidth, destHeight);
392
+ return;
393
+ }
394
+ const effective = effectiveSourceSize(sourceWidth, sourceHeight, turns);
395
+ context.save();
396
+ // Innermost-to-outermost: rotate raw -> effective coords, shift the crop
397
+ // origin to (0,0), scale the crop onto the destination.
398
+ context.scale(destWidth / crop.width, destHeight / crop.height);
399
+ context.translate(-crop.x, -crop.y);
400
+ if (turns === 1) {
401
+ context.translate(effective.width, 0);
402
+ }
403
+ else if (turns === 2) {
404
+ context.translate(effective.width, effective.height);
405
+ }
406
+ else {
407
+ context.translate(0, effective.height);
408
+ }
409
+ context.rotate((turns * Math.PI) / 2);
410
+ context.drawImage(image, 0, 0, sourceWidth, sourceHeight);
411
+ context.restore();
412
+ }
413
+ /** Decode a file and reject empty/unreadable images with a user-facing error. */
414
+ async function loadDecodedImage(file) {
415
+ const image = await loadImageElement(file);
416
+ const sourceWidth = image.naturalWidth || image.width;
417
+ const sourceHeight = image.naturalHeight || image.height;
418
+ if (!sourceWidth || !sourceHeight) {
419
+ throw new Error('That image appears to be empty.');
420
+ }
421
+ return { image, sourceWidth, sourceHeight };
422
+ }
423
+ /** Encode `dataUrl` down the quality ladder until it fits the API's cap. */
424
+ function encodeUnderCap(canvas, ladder) {
425
+ let dataUrl = '';
426
+ for (const quality of ladder) {
427
+ dataUrl = canvas.toDataURL(CARD_IMAGE_MIME_TYPE, quality);
428
+ if (dataUrl.length <= MAX_IMAGE_DATA_URL_LENGTH)
429
+ break;
430
+ }
431
+ if (dataUrl.length > MAX_IMAGE_DATA_URL_LENGTH) {
432
+ throw new Error('That photo is too large to process even after compression. Try a photo taken at a lower resolution.');
433
+ }
434
+ return dataUrl;
435
+ }
436
+ /**
437
+ * Draw a planned crop and encode it — the shared tail of
438
+ * {@link cropImageFileToCard} and {@link cropImageFileToBox}, so both paths
439
+ * produce byte-identical output for the same plan.
440
+ */
441
+ function encodeCardCrop(image, sourceWidth, sourceHeight, plan, fileName) {
442
+ const { output } = plan;
443
+ const canvas = document.createElement('canvas');
444
+ canvas.width = output.width;
445
+ canvas.height = output.height;
446
+ const context = canvas.getContext('2d');
447
+ if (!context) {
448
+ throw new Error('This browser could not process the image.');
449
+ }
450
+ drawCardCrop(context, image, sourceWidth, sourceHeight, plan, output.width, output.height);
451
+ const dataUrl = encodeUnderCap(canvas, QUALITY_LADDER);
452
+ const blob = dataUrlToBlob(dataUrl);
453
+ return {
454
+ dataUrl,
455
+ file: new File([blob], fileName, { type: CARD_IMAGE_MIME_TYPE }),
456
+ previewUrl: URL.createObjectURL(blob),
457
+ width: output.width,
458
+ height: output.height,
459
+ };
460
+ }
461
+ /**
462
+ * Prepare the FULL photo for extraction: decode, downscale only when the long
463
+ * edge exceeds {@link CARD_PHOTO_MAX_LONG_EDGE} — no crop, no aspect change,
464
+ * no rotation — and JPEG-encode under the API's size cap.
465
+ *
466
+ * The returned `dataUrl` is what goes to `POST /api/secrets/cards/extract`;
467
+ * the returned dimensions are the frame the response's box fractions apply to.
468
+ *
469
+ * Throws with a user-presentable message when the file is not decodable or
470
+ * cannot be squeezed under the cap.
471
+ */
472
+ export async function prepareCardPhoto(file) {
473
+ const { image, sourceWidth, sourceHeight } = await loadDecodedImage(file);
474
+ const scale = Math.min(1, CARD_PHOTO_MAX_LONG_EDGE / Math.max(sourceWidth, sourceHeight));
475
+ const width = Math.max(1, Math.round(sourceWidth * scale));
476
+ const height = Math.max(1, Math.round(sourceHeight * scale));
477
+ const canvas = document.createElement('canvas');
478
+ canvas.width = width;
479
+ canvas.height = height;
480
+ const context = canvas.getContext('2d');
481
+ if (!context) {
482
+ throw new Error('This browser could not process the image.');
483
+ }
484
+ context.drawImage(image, 0, 0, sourceWidth, sourceHeight, 0, 0, width, height);
485
+ return { dataUrl: encodeUnderCap(canvas, PHOTO_QUALITY_LADDER), width, height };
486
+ }
487
+ /**
488
+ * Crop, downscale and JPEG-encode a captured file to the card rectangle.
489
+ *
490
+ * `options` may carry user adjustments (`zoom`, `panX`, `panY`,
491
+ * `quarterTurns`); with none supplied the behavior is the historical auto-fit
492
+ * centred crop, unchanged.
493
+ *
494
+ * Throws with a user-presentable message when the file is not decodable or
495
+ * cannot be squeezed under the API's size cap.
496
+ */
497
+ export async function cropImageFileToCard(file, options = {}) {
498
+ const { image, sourceWidth, sourceHeight } = await loadDecodedImage(file);
499
+ const plan = planCardCrop(sourceWidth, sourceHeight, options);
500
+ return encodeCardCrop(image, sourceWidth, sourceHeight, plan, options.fileName ?? 'card.jpg');
501
+ }
502
+ /**
503
+ * Crop, downscale and JPEG-encode a captured file from an explicit fractional
504
+ * box — the AI-located card. The rect comes from {@link cropRectFromBox}
505
+ * (margin, aspect snap, clamping) and is rendered by the same
506
+ * {@link drawCardCrop} + quality-ladder path as every other crop.
507
+ *
508
+ * The crop is rendered from the RAW capture at full resolution: the box's
509
+ * fractions apply to the (possibly downscaled) prepared photo and to the raw
510
+ * frame alike, and the raw frame has more pixels to give.
511
+ */
512
+ export async function cropImageFileToBox(file, box, options = {}) {
513
+ const { image, sourceWidth, sourceHeight } = await loadDecodedImage(file);
514
+ const quarterTurns = normalizeQuarterTurns(box.quarterTurns);
515
+ const crop = cropRectFromBox(sourceWidth, sourceHeight, box, options.aspectRatio, options.marginFraction);
516
+ const output = computeOutputSize(crop.width, crop.height, options.maxLongEdge);
517
+ return encodeCardCrop(image, sourceWidth, sourceHeight, { crop, output, quarterTurns }, options.fileName ?? 'card.jpg');
518
+ }
@@ -0,0 +1,6 @@
1
+ export * from './cardExpiry.js';
2
+ export * from './cardFormat.js';
3
+ export * from './cardImage.js';
4
+ export * from './useCardImport.js';
5
+ export * from './useCardRenewal.js';
6
+ export * from './useCards.js';
@@ -0,0 +1,7 @@
1
+ // Payment cards: the card hooks (list, scan import, renewal) and the expiry, format and image helpers. No component.
2
+ export * from './cardExpiry.js';
3
+ export * from './cardFormat.js';
4
+ export * from './cardImage.js';
5
+ export * from './useCardImport.js';
6
+ export * from './useCardRenewal.js';
7
+ export * from './useCards.js';
@@ -0,0 +1,137 @@
1
+ import { type AttachmentRole, type CardExtractionResult, type ExtractCardRequest, type SecretType } from '../../core/headless/types.js';
2
+ import type { CroppedCardImage, PreparedCardPhoto } from './cardImage.js';
3
+ /**
4
+ * Confidence at or below which a field is flagged for the user to check.
5
+ *
6
+ * A flag costs one glance; a wrong digit that ships silently costs a declined
7
+ * payment, so this is set generously rather than tightly.
8
+ */
9
+ export declare const LOW_CONFIDENCE_THRESHOLD = 0.7;
10
+ /**
11
+ * A captured photo of one card side: the raw file, the prepared full-frame
12
+ * data URL that goes to the extraction endpoint, and a preview object URL.
13
+ * The page that creates it owns (and must revoke) the preview URL.
14
+ */
15
+ export interface CapturedCardPhoto {
16
+ file: File;
17
+ prepared: PreparedCardPhoto;
18
+ previewUrl: string;
19
+ }
20
+ /** A captured card side, cropped to the card and ready to upload/attach. */
21
+ export interface CapturedCardSide {
22
+ role: AttachmentRole;
23
+ image: CroppedCardImage;
24
+ }
25
+ /**
26
+ * A failure rendered for a human.
27
+ *
28
+ * `detail` is written to tell the user what to do next, which is why the
29
+ * per-code branches exist at all — "Too many requests" is true for both the
30
+ * burst limiter and the daily budget, and useless for either.
31
+ */
32
+ export interface CardExtractionMessage {
33
+ title: string;
34
+ detail: string;
35
+ /** True when only an administrator can clear the condition. */
36
+ adminActionRequired: boolean;
37
+ /** True when retrying the same images could plausibly succeed. */
38
+ retryable: boolean;
39
+ /**
40
+ * Where an administrator fixes it, when the page should offer a link there
41
+ * (shown only to a viewer who can open it: `ai_config:read`).
42
+ */
43
+ adminLink?: {
44
+ label: string;
45
+ to: string;
46
+ };
47
+ }
48
+ /** The Console's AI page, where AI is switched on and set up. */
49
+ export declare const AI_SETTINGS_PATH = "/admin/settings/ai";
50
+ /** AI switched off by an administrator (the platform kill switch's 403). */
51
+ export declare const AI_DISABLED_MESSAGE: CardExtractionMessage;
52
+ /** AI on, but the provider, model or key is not set up (503 `AI_NOT_CONFIGURED`). */
53
+ export declare const AI_NOT_CONFIGURED_MESSAGE: CardExtractionMessage;
54
+ /** The caller may not use AI (a `403` without `AI_DISABLED`: no `ai:use`). */
55
+ export declare const AI_FORBIDDEN_MESSAGE: CardExtractionMessage;
56
+ /**
57
+ * Map an extraction failure to an actionable message.
58
+ *
59
+ * AI switched off is checked first: the platform kill switch answers `403` with
60
+ * top-level code `FORBIDDEN` and `details.reason: 'AI_DISABLED'` (E8.1; it was a
61
+ * 503 before). Any other 403 means the caller lacks `ai:use`. Then the API's
62
+ * `AI_*` `code`, then the HTTP status. Codes are matched against the known
63
+ * `AI_*` set rather than trusted blindly, so a status-derived stand-in
64
+ * ('TOO_MANY_REQUESTS', 'BAD_REQUEST') falls through to the status branch.
65
+ * Message text is never parsed: it is copy, and it will be reworded.
66
+ */
67
+ export declare function describeCardExtractionError(error: unknown): CardExtractionMessage;
68
+ /**
69
+ * Fields that are typed by hand and NEVER seeded from an extraction: the card
70
+ * security codes (E10.5, issue #96; AGENTS.md AI rule 3). Since E8.1 the API
71
+ * always answers them `null` (confidence 0); the review form starts them empty
72
+ * whatever arrives, so the code a user saves is always the one they typed.
73
+ */
74
+ export declare const MANUAL_ONLY_CARD_FIELDS: ReadonlySet<string>;
75
+ /**
76
+ * Seed the review form from an extraction.
77
+ *
78
+ * Every value becomes a string because the form edits strings. The security
79
+ * codes ({@link MANUAL_ONLY_CARD_FIELDS}) are never seeded: they always start
80
+ * empty, whatever the extraction returned, and the user types them.
81
+ */
82
+ export declare function toReviewValues(extraction: CardExtractionResult | null): Record<string, string>;
83
+ /**
84
+ * The fields whose seeded value came from the extraction (non-empty and not
85
+ * manual-only), so the review form can mark them "read by AI".
86
+ */
87
+ export declare function aiSeededFields(extraction: CardExtractionResult | null): Set<string>;
88
+ /**
89
+ * Default name for the imported secret, e.g. `Visa ••••4242`.
90
+ *
91
+ * Only the last four digits appear: a secret's name is metadata that shows up
92
+ * in lists, search results and audit records, none of which should carry a PAN.
93
+ */
94
+ export declare function buildDefaultCardName(network: string | null | undefined, number: string | null | undefined): string;
95
+ export interface SaveCardInput {
96
+ name: string;
97
+ values: Record<string, string>;
98
+ images: CapturedCardSide[];
99
+ }
100
+ export interface SaveCardOutcome {
101
+ secretId: string;
102
+ /**
103
+ * Set when the card itself saved but one or more images could not be
104
+ * attached. The secret is kept — losing hand-typed card details over a failed
105
+ * image upload would be a worse outcome — and the orphaned uploads are
106
+ * deleted.
107
+ */
108
+ attachmentWarning: string | null;
109
+ }
110
+ interface UseCardImportResult {
111
+ cardType: SecretType | null;
112
+ isTypeLoading: boolean;
113
+ typeError: string | null;
114
+ extraction: CardExtractionResult | null;
115
+ extractionError: CardExtractionMessage | null;
116
+ isExtracting: boolean;
117
+ /**
118
+ * Run the extraction on the prepared FULL photos. NEVER REJECTS — a failure
119
+ * resolves to `null` and lands in `extractionError`, so the caller always
120
+ * advances to review.
121
+ */
122
+ runExtraction: (photos: ExtractCardRequest) => Promise<CardExtractionResult | null>;
123
+ isSaving: boolean;
124
+ saveError: string | null;
125
+ saveCard: (input: SaveCardInput) => Promise<SaveCardOutcome | null>;
126
+ /** Delete anything this flow created. Safe to call repeatedly. */
127
+ abandonImport: () => Promise<void>;
128
+ }
129
+ /**
130
+ * Network and cleanup side of the card import wizard.
131
+ *
132
+ * The page owns the step, the captured images and the form values; this hook
133
+ * owns everything that touches the server and, crucially, everything that has
134
+ * to be undone if the user walks away.
135
+ */
136
+ export declare function useCardImport(): UseCardImportResult;
137
+ export {};