@prabhask5/stellar-engine 1.1.7 → 1.1.8

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 (191) hide show
  1. package/README.md +4 -1
  2. package/dist/actions/remoteChange.d.ts +143 -18
  3. package/dist/actions/remoteChange.d.ts.map +1 -1
  4. package/dist/actions/remoteChange.js +182 -58
  5. package/dist/actions/remoteChange.js.map +1 -1
  6. package/dist/actions/truncateTooltip.d.ts +26 -12
  7. package/dist/actions/truncateTooltip.d.ts.map +1 -1
  8. package/dist/actions/truncateTooltip.js +89 -34
  9. package/dist/actions/truncateTooltip.js.map +1 -1
  10. package/dist/auth/admin.d.ts +40 -3
  11. package/dist/auth/admin.d.ts.map +1 -1
  12. package/dist/auth/admin.js +45 -5
  13. package/dist/auth/admin.js.map +1 -1
  14. package/dist/auth/crypto.d.ts +55 -5
  15. package/dist/auth/crypto.d.ts.map +1 -1
  16. package/dist/auth/crypto.js +58 -5
  17. package/dist/auth/crypto.js.map +1 -1
  18. package/dist/auth/deviceVerification.d.ts +236 -20
  19. package/dist/auth/deviceVerification.d.ts.map +1 -1
  20. package/dist/auth/deviceVerification.js +293 -40
  21. package/dist/auth/deviceVerification.js.map +1 -1
  22. package/dist/auth/displayUtils.d.ts +98 -0
  23. package/dist/auth/displayUtils.d.ts.map +1 -0
  24. package/dist/auth/displayUtils.js +133 -0
  25. package/dist/auth/displayUtils.js.map +1 -0
  26. package/dist/auth/loginGuard.d.ts +108 -14
  27. package/dist/auth/loginGuard.d.ts.map +1 -1
  28. package/dist/auth/loginGuard.js +153 -31
  29. package/dist/auth/loginGuard.js.map +1 -1
  30. package/dist/auth/offlineCredentials.d.ts +132 -15
  31. package/dist/auth/offlineCredentials.d.ts.map +1 -1
  32. package/dist/auth/offlineCredentials.js +167 -23
  33. package/dist/auth/offlineCredentials.js.map +1 -1
  34. package/dist/auth/offlineLogin.d.ts +96 -10
  35. package/dist/auth/offlineLogin.d.ts.map +1 -1
  36. package/dist/auth/offlineLogin.js +82 -15
  37. package/dist/auth/offlineLogin.js.map +1 -1
  38. package/dist/auth/offlineSession.d.ts +83 -9
  39. package/dist/auth/offlineSession.d.ts.map +1 -1
  40. package/dist/auth/offlineSession.js +104 -13
  41. package/dist/auth/offlineSession.js.map +1 -1
  42. package/dist/auth/resolveAuthState.d.ts +70 -8
  43. package/dist/auth/resolveAuthState.d.ts.map +1 -1
  44. package/dist/auth/resolveAuthState.js +142 -46
  45. package/dist/auth/resolveAuthState.js.map +1 -1
  46. package/dist/auth/singleUser.d.ts +390 -37
  47. package/dist/auth/singleUser.d.ts.map +1 -1
  48. package/dist/auth/singleUser.js +500 -99
  49. package/dist/auth/singleUser.js.map +1 -1
  50. package/dist/bin/install-pwa.d.ts +18 -2
  51. package/dist/bin/install-pwa.d.ts.map +1 -1
  52. package/dist/bin/install-pwa.js +801 -25
  53. package/dist/bin/install-pwa.js.map +1 -1
  54. package/dist/config.d.ts +132 -12
  55. package/dist/config.d.ts.map +1 -1
  56. package/dist/config.js +87 -9
  57. package/dist/config.js.map +1 -1
  58. package/dist/conflicts.d.ts +246 -23
  59. package/dist/conflicts.d.ts.map +1 -1
  60. package/dist/conflicts.js +495 -46
  61. package/dist/conflicts.js.map +1 -1
  62. package/dist/data.d.ts +338 -18
  63. package/dist/data.d.ts.map +1 -1
  64. package/dist/data.js +385 -34
  65. package/dist/data.js.map +1 -1
  66. package/dist/database.d.ts +72 -14
  67. package/dist/database.d.ts.map +1 -1
  68. package/dist/database.js +120 -29
  69. package/dist/database.js.map +1 -1
  70. package/dist/debug.d.ts +77 -1
  71. package/dist/debug.d.ts.map +1 -1
  72. package/dist/debug.js +88 -1
  73. package/dist/debug.js.map +1 -1
  74. package/dist/deviceId.d.ts +38 -7
  75. package/dist/deviceId.d.ts.map +1 -1
  76. package/dist/deviceId.js +68 -10
  77. package/dist/deviceId.js.map +1 -1
  78. package/dist/engine.d.ts +175 -3
  79. package/dist/engine.d.ts.map +1 -1
  80. package/dist/engine.js +756 -109
  81. package/dist/engine.js.map +1 -1
  82. package/dist/entries/actions.d.ts +13 -0
  83. package/dist/entries/actions.d.ts.map +1 -1
  84. package/dist/entries/actions.js +26 -1
  85. package/dist/entries/actions.js.map +1 -1
  86. package/dist/entries/auth.d.ts +16 -0
  87. package/dist/entries/auth.d.ts.map +1 -1
  88. package/dist/entries/auth.js +73 -1
  89. package/dist/entries/auth.js.map +1 -1
  90. package/dist/entries/config.d.ts +12 -0
  91. package/dist/entries/config.d.ts.map +1 -1
  92. package/dist/entries/config.js +18 -1
  93. package/dist/entries/config.js.map +1 -1
  94. package/dist/entries/kit.d.ts +11 -0
  95. package/dist/entries/kit.d.ts.map +1 -1
  96. package/dist/entries/kit.js +52 -2
  97. package/dist/entries/kit.js.map +1 -1
  98. package/dist/entries/stores.d.ts +11 -0
  99. package/dist/entries/stores.d.ts.map +1 -1
  100. package/dist/entries/stores.js +43 -2
  101. package/dist/entries/stores.js.map +1 -1
  102. package/dist/entries/types.d.ts +10 -0
  103. package/dist/entries/types.d.ts.map +1 -1
  104. package/dist/entries/types.js +10 -0
  105. package/dist/entries/types.js.map +1 -1
  106. package/dist/entries/utils.d.ts +6 -0
  107. package/dist/entries/utils.d.ts.map +1 -1
  108. package/dist/entries/utils.js +22 -1
  109. package/dist/entries/utils.js.map +1 -1
  110. package/dist/entries/vite.d.ts +17 -0
  111. package/dist/entries/vite.d.ts.map +1 -1
  112. package/dist/entries/vite.js +24 -1
  113. package/dist/entries/vite.js.map +1 -1
  114. package/dist/index.d.ts +31 -0
  115. package/dist/index.d.ts.map +1 -1
  116. package/dist/index.js +175 -20
  117. package/dist/index.js.map +1 -1
  118. package/dist/kit/auth.d.ts +60 -5
  119. package/dist/kit/auth.d.ts.map +1 -1
  120. package/dist/kit/auth.js +45 -4
  121. package/dist/kit/auth.js.map +1 -1
  122. package/dist/kit/confirm.d.ts +93 -12
  123. package/dist/kit/confirm.d.ts.map +1 -1
  124. package/dist/kit/confirm.js +103 -16
  125. package/dist/kit/confirm.js.map +1 -1
  126. package/dist/kit/loads.d.ts +150 -23
  127. package/dist/kit/loads.d.ts.map +1 -1
  128. package/dist/kit/loads.js +140 -24
  129. package/dist/kit/loads.js.map +1 -1
  130. package/dist/kit/server.d.ts +142 -10
  131. package/dist/kit/server.d.ts.map +1 -1
  132. package/dist/kit/server.js +158 -15
  133. package/dist/kit/server.js.map +1 -1
  134. package/dist/kit/sw.d.ts +152 -23
  135. package/dist/kit/sw.d.ts.map +1 -1
  136. package/dist/kit/sw.js +182 -26
  137. package/dist/kit/sw.js.map +1 -1
  138. package/dist/queue.d.ts +274 -0
  139. package/dist/queue.d.ts.map +1 -1
  140. package/dist/queue.js +556 -38
  141. package/dist/queue.js.map +1 -1
  142. package/dist/realtime.d.ts +241 -27
  143. package/dist/realtime.d.ts.map +1 -1
  144. package/dist/realtime.js +633 -109
  145. package/dist/realtime.js.map +1 -1
  146. package/dist/runtime/runtimeConfig.d.ts +91 -8
  147. package/dist/runtime/runtimeConfig.d.ts.map +1 -1
  148. package/dist/runtime/runtimeConfig.js +146 -19
  149. package/dist/runtime/runtimeConfig.js.map +1 -1
  150. package/dist/stores/authState.d.ts +150 -11
  151. package/dist/stores/authState.d.ts.map +1 -1
  152. package/dist/stores/authState.js +169 -17
  153. package/dist/stores/authState.js.map +1 -1
  154. package/dist/stores/network.d.ts +39 -0
  155. package/dist/stores/network.d.ts.map +1 -1
  156. package/dist/stores/network.js +169 -16
  157. package/dist/stores/network.js.map +1 -1
  158. package/dist/stores/remoteChanges.d.ts +327 -52
  159. package/dist/stores/remoteChanges.d.ts.map +1 -1
  160. package/dist/stores/remoteChanges.js +337 -75
  161. package/dist/stores/remoteChanges.js.map +1 -1
  162. package/dist/stores/sync.d.ts +130 -0
  163. package/dist/stores/sync.d.ts.map +1 -1
  164. package/dist/stores/sync.js +167 -7
  165. package/dist/stores/sync.js.map +1 -1
  166. package/dist/supabase/auth.d.ts +325 -18
  167. package/dist/supabase/auth.d.ts.map +1 -1
  168. package/dist/supabase/auth.js +374 -26
  169. package/dist/supabase/auth.js.map +1 -1
  170. package/dist/supabase/client.d.ts +79 -6
  171. package/dist/supabase/client.d.ts.map +1 -1
  172. package/dist/supabase/client.js +158 -15
  173. package/dist/supabase/client.js.map +1 -1
  174. package/dist/supabase/validate.d.ts +101 -7
  175. package/dist/supabase/validate.d.ts.map +1 -1
  176. package/dist/supabase/validate.js +117 -8
  177. package/dist/supabase/validate.js.map +1 -1
  178. package/dist/sw/build/vite-plugin.d.ts +55 -10
  179. package/dist/sw/build/vite-plugin.d.ts.map +1 -1
  180. package/dist/sw/build/vite-plugin.js +77 -18
  181. package/dist/sw/build/vite-plugin.js.map +1 -1
  182. package/dist/sw/sw.js +99 -44
  183. package/dist/types.d.ts +150 -26
  184. package/dist/types.d.ts.map +1 -1
  185. package/dist/types.js +12 -10
  186. package/dist/types.js.map +1 -1
  187. package/dist/utils.d.ts +55 -13
  188. package/dist/utils.d.ts.map +1 -1
  189. package/dist/utils.js +83 -22
  190. package/dist/utils.js.map +1 -1
  191. package/package.json +1 -1
@@ -1,14 +1,159 @@
1
+ /**
2
+ * @fileoverview Supabase Authentication Module
3
+ *
4
+ * Provides a complete authentication layer on top of Supabase Auth, with
5
+ * built-in support for:
6
+ *
7
+ * - **Offline credential caching**: On successful login, credentials are hashed
8
+ * and persisted locally so that users can re-authenticate even when the device
9
+ * is offline (airplane mode, poor connectivity, etc.).
10
+ *
11
+ * - **Login guard / brute-force protection**: Every sign-in attempt passes
12
+ * through a local pre-check (`loginGuard`) that enforces rate-limiting and
13
+ * multi-user strategy rules *before* hitting the Supabase API.
14
+ *
15
+ * - **Device verification (optional)**: When enabled in the engine config, an
16
+ * untrusted device will trigger an OTP flow and the user will not receive a
17
+ * session until the device is verified.
18
+ *
19
+ * - **Graceful session recovery**: `getSession()` falls back to localStorage
20
+ * when the device is offline, ensuring the app can still render authenticated
21
+ * views with stale-but-usable session data.
22
+ *
23
+ * Security considerations:
24
+ * - Passwords are hashed before being stored in the offline credential cache.
25
+ * - The `changePassword` flow verifies the current password locally (if a
26
+ * cached hash exists) or via a Supabase re-authentication call.
27
+ * - Corrupted sessions are detected and automatically cleared to prevent
28
+ * infinite error loops.
29
+ * - Sign-out follows a strict 10-step teardown sequence to ensure no stale
30
+ * data leaks across user boundaries.
31
+ *
32
+ * Integration patterns:
33
+ * - Consumed by UI auth screens (login, signup, profile, password change).
34
+ * - Works in tandem with `./client.ts` (lazy Supabase singleton) and
35
+ * `../engine.ts` (sync engine lifecycle).
36
+ * - Offline credential helpers live in `../auth/offlineCredentials.ts`.
37
+ *
38
+ * @module supabase/auth
39
+ */
1
40
  import type { User, Session } from '@supabase/supabase-js';
41
+ /**
42
+ * Standardized response shape returned by all authentication operations.
43
+ *
44
+ * Every auth function in this module returns this interface so that callers
45
+ * can rely on a single, predictable contract for success/failure handling.
46
+ */
2
47
  export interface AuthResponse {
48
+ /** The authenticated Supabase user, or `null` if authentication failed. */
3
49
  user: User | null;
50
+ /** The active session, or `null` if not yet established (e.g. device verification pending). */
4
51
  session: Session | null;
52
+ /** A human-readable error message, or `null` on success. */
5
53
  error: string | null;
54
+ /**
55
+ * When `true`, the device has not been verified and the caller must
56
+ * present a device-verification OTP input before granting access.
57
+ * Only set when `auth.deviceVerification.enabled` is `true` in the engine config.
58
+ */
6
59
  deviceVerificationRequired?: boolean;
60
+ /**
61
+ * A partially-masked version of the user's email (e.g. `j***@example.com`)
62
+ * shown during device verification so the user knows where to look for the OTP.
63
+ */
7
64
  maskedEmail?: string;
65
+ /**
66
+ * If the login guard rejected the attempt due to rate-limiting, this value
67
+ * indicates how many milliseconds the caller should wait before retrying.
68
+ */
8
69
  retryAfterMs?: number;
9
70
  }
71
+ /**
72
+ * Authenticate a user with email and password.
73
+ *
74
+ * Flow:
75
+ * 1. Run `preCheckLogin` to enforce local brute-force / rate-limit rules.
76
+ * 2. Call `supabase.auth.signInWithPassword`.
77
+ * 3. On success, cache credentials for offline re-authentication.
78
+ * 4. If device verification is enabled, check trust status and optionally
79
+ * trigger an OTP challenge instead of returning the session.
80
+ *
81
+ * @param email - The user's email address.
82
+ * @param password - The user's plaintext password (hashed before caching).
83
+ * @returns An {@link AuthResponse} indicating success, failure, or a device
84
+ * verification challenge.
85
+ *
86
+ * @example
87
+ * ```ts
88
+ * const result = await signIn('user@example.com', 's3cret');
89
+ * if (result.deviceVerificationRequired) {
90
+ * // Show OTP input, display result.maskedEmail
91
+ * } else if (result.error) {
92
+ * // Show error
93
+ * } else {
94
+ * // Logged in — result.session is available
95
+ * }
96
+ * ```
97
+ *
98
+ * @see {@link preCheckLogin} — local credential & rate-limit guard
99
+ * @see {@link cacheOfflineCredentials} — offline credential persistence
100
+ */
10
101
  export declare function signIn(email: string, password: string): Promise<AuthResponse>;
102
+ /**
103
+ * Register a new user account with Supabase.
104
+ *
105
+ * Profile data is transformed via the optional `auth.profileToMetadata`
106
+ * config hook before being sent as `user_metadata` so that the host app
107
+ * can normalize field names.
108
+ *
109
+ * @param email - The new user's email address.
110
+ * @param password - The desired password (Supabase enforces its own strength rules).
111
+ * @param profileData - Arbitrary profile fields (e.g. `{ display_name, avatar_url }`).
112
+ * @returns An {@link AuthResponse}. Note: `session` may be `null` if email
113
+ * confirmation is required by the Supabase project settings.
114
+ *
115
+ * @example
116
+ * ```ts
117
+ * const result = await signUp('new@user.com', 'p@ssw0rd', { display_name: 'Ada' });
118
+ * if (result.error) { ... }
119
+ * ```
120
+ *
121
+ * @see {@link getConfirmRedirectUrl} — determines the email confirmation link target
122
+ */
11
123
  export declare function signUp(email: string, password: string, profileData: Record<string, unknown>): Promise<AuthResponse>;
124
+ /**
125
+ * Sign the current user out and perform a full teardown of local state.
126
+ *
127
+ * The teardown follows a strict **10-step sequence** to ensure no stale data
128
+ * leaks between user sessions:
129
+ *
130
+ * 1. Stop the sync engine (dynamic import avoids circular deps).
131
+ * 2. Clear the pending sync queue (unless `preserveLocalData` is set).
132
+ * 3. Clear the local cache (unless `preserveLocalData` is set).
133
+ * 4. Clear the offline session token.
134
+ * 5. Clear offline credentials (only when online, to preserve offline re-login).
135
+ * 6. Call `supabase.auth.signOut()`.
136
+ * 7. Remove all `sb-*` keys from localStorage (Supabase internal storage).
137
+ * 8. Reset the login guard (brute-force counters).
138
+ * 9. Reset the sync status store.
139
+ * 10. Reset the auth state store.
140
+ *
141
+ * Each step is wrapped in its own try/catch so that a failure in one step
142
+ * does not prevent subsequent cleanup from running.
143
+ *
144
+ * @param options - Optional flags to control teardown behavior.
145
+ * @param options.preserveOfflineCredentials - When `true`, offline credentials
146
+ * are kept so the user can re-authenticate without network access.
147
+ * @param options.preserveLocalData - When `true`, pending sync queue and local
148
+ * cache are retained (useful for "switch account" scenarios).
149
+ * @returns An object with an `error` field (`null` on success).
150
+ *
151
+ * @example
152
+ * ```ts
153
+ * await signOut(); // full teardown
154
+ * await signOut({ preserveLocalData: true }); // keep cached data
155
+ * ```
156
+ */
12
157
  export declare function signOut(options?: {
13
158
  preserveOfflineCredentials?: boolean;
14
159
  preserveLocalData?: boolean;
@@ -16,64 +161,226 @@ export declare function signOut(options?: {
16
161
  error: string | null;
17
162
  }>;
18
163
  /**
19
- * Get current Supabase session
20
- * When offline, returns the cached session from localStorage even if expired
21
- * (the caller should handle offline mode appropriately)
164
+ * Get the current Supabase session.
165
+ *
166
+ * When the device is **online**, this delegates to `supabase.auth.getSession()`
167
+ * which may trigger a token refresh if the access token is close to expiry.
168
+ *
169
+ * When the device is **offline**, or if the Supabase call fails with a
170
+ * corrupted-session error, this falls back to reading the session directly
171
+ * from localStorage via {@link getSessionFromStorage}. The returned session
172
+ * may be expired, but callers can use {@link isSessionExpired} to check and
173
+ * should handle offline mode appropriately (e.g. show cached data, queue
174
+ * mutations for later sync).
175
+ *
176
+ * @returns The current `Session` object, or `null` if no valid session exists.
177
+ *
178
+ * @example
179
+ * ```ts
180
+ * const session = await getSession();
181
+ * if (session && !isSessionExpired(session)) {
182
+ * // Fully authenticated
183
+ * }
184
+ * ```
185
+ *
186
+ * @see {@link getSessionFromStorage} — direct localStorage fallback
187
+ * @see {@link isSessionExpired} — expiry check helper
188
+ * @see {@link getValidSession} — combined convenience wrapper
22
189
  */
23
190
  export declare function getSession(): Promise<Session | null>;
24
191
  /**
25
- * Check if a session's access token is expired
192
+ * Check whether a session's access token has expired.
193
+ *
194
+ * The `expires_at` field on a Supabase session is a **Unix timestamp in
195
+ * seconds**. We compare it against `Date.now() / 1000` (which is in
196
+ * milliseconds, hence the division).
197
+ *
198
+ * @param session - The session to check, or `null`.
199
+ * @returns `true` if the session is `null`, missing `expires_at`, or past
200
+ * its expiry time; `false` otherwise.
201
+ *
202
+ * @example
203
+ * ```ts
204
+ * if (isSessionExpired(session)) {
205
+ * // Prompt re-authentication or attempt token refresh
206
+ * }
207
+ * ```
26
208
  */
27
209
  export declare function isSessionExpired(session: Session | null): boolean;
210
+ /**
211
+ * Extract the user's profile from their Supabase `user_metadata`.
212
+ *
213
+ * If the engine config provides a custom `auth.profileExtractor`, it is
214
+ * invoked to transform the raw metadata into the app's profile shape.
215
+ * Otherwise the raw `user_metadata` object is returned as-is.
216
+ *
217
+ * @param user - The Supabase `User` object (may be `null`).
218
+ * @returns A key-value record representing the user's profile fields.
219
+ *
220
+ * @example
221
+ * ```ts
222
+ * const profile = getUserProfile(session.user);
223
+ * console.log(profile.display_name);
224
+ * ```
225
+ */
28
226
  export declare function getUserProfile(user: User | null): Record<string, unknown>;
29
227
  /**
30
- * Update user profile
31
- * Also updates cached offline credentials
228
+ * Update the current user's profile metadata on Supabase.
229
+ *
230
+ * The profile data is transformed through `auth.profileToMetadata` (if
231
+ * configured) before being sent. On success the offline credential cache
232
+ * is also updated so that the profile stays consistent across online and
233
+ * offline modes.
234
+ *
235
+ * @param profile - The updated profile fields to persist.
236
+ * @returns An object with an `error` field (`null` on success).
237
+ *
238
+ * @example
239
+ * ```ts
240
+ * const { error } = await updateProfile({ display_name: 'New Name' });
241
+ * ```
242
+ *
243
+ * @see {@link updateOfflineCredentialsProfile} — keeps the offline cache in sync
32
244
  */
33
245
  export declare function updateProfile(profile: Record<string, unknown>): Promise<{
34
246
  error: string | null;
35
247
  }>;
36
248
  /**
37
- * Change user password
38
- * Verifies current password first, then updates
39
- * Also updates cached offline credentials
249
+ * Change the current user's password.
250
+ *
251
+ * Security flow:
252
+ * 1. Retrieve the current session to obtain the user's email.
253
+ * 2. **Verify the current password** — two strategies:
254
+ * a. If an offline credential cache exists and the email matches, compare
255
+ * hashes locally (avoids a network round-trip and an extra Supabase call).
256
+ * b. Otherwise, fall back to `supabase.auth.signInWithPassword` to verify
257
+ * against the server.
258
+ * 3. Call `supabase.auth.updateUser({ password })` to set the new password.
259
+ * 4. Update the offline credential cache with the new password hash.
260
+ *
261
+ * @param currentPassword - The user's current password (for verification).
262
+ * @param newPassword - The desired new password.
263
+ * @returns An object with an `error` field (`null` on success).
264
+ *
265
+ * @throws Never throws — all errors are returned in the `error` field.
266
+ *
267
+ * @example
268
+ * ```ts
269
+ * const { error } = await changePassword('oldPass', 'newPass');
270
+ * if (error) { alert(error); }
271
+ * ```
272
+ *
273
+ * @see {@link hashValue} — used for local password comparison
274
+ * @see {@link updateOfflineCredentialsPassword} — keeps the offline cache in sync
40
275
  */
41
276
  export declare function changePassword(currentPassword: string, newPassword: string): Promise<{
42
277
  error: string | null;
43
278
  }>;
44
279
  /**
45
280
  * Initiate an email change for the current user.
46
- * Supabase sends a confirmation email to the new address.
281
+ *
282
+ * Supabase sends a confirmation link to the **new** email address. The
283
+ * change is not applied until the user clicks that link and the app calls
284
+ * {@link completeEmailChange}.
285
+ *
286
+ * @param newEmail - The desired new email address.
287
+ * @returns An object indicating whether a confirmation email was sent, plus
288
+ * any error that occurred.
289
+ *
290
+ * @example
291
+ * ```ts
292
+ * const { error, confirmationRequired } = await changeEmail('new@example.com');
293
+ * if (confirmationRequired) {
294
+ * // Tell the user to check their inbox
295
+ * }
296
+ * ```
297
+ *
298
+ * @see {@link completeEmailChange} — finishes the flow after confirmation
47
299
  */
48
300
  export declare function changeEmail(newEmail: string): Promise<{
49
301
  error: string | null;
50
302
  confirmationRequired: boolean;
51
303
  }>;
52
304
  /**
53
- * Complete email change after the user confirms via the email link.
54
- * Refreshes session to pick up the new email and updates offline credentials.
305
+ * Complete an email change after the user confirms via the email link.
306
+ *
307
+ * Refreshes the Supabase session to pick up the updated email address,
308
+ * then updates the offline credential cache so that offline login uses
309
+ * the new email.
310
+ *
311
+ * @returns An object containing the new email and/or an error message.
312
+ *
313
+ * @example
314
+ * ```ts
315
+ * const { error, newEmail } = await completeEmailChange();
316
+ * if (!error) {
317
+ * console.log(`Email changed to ${newEmail}`);
318
+ * }
319
+ * ```
320
+ *
321
+ * @see {@link changeEmail} — initiates the flow
55
322
  */
56
323
  export declare function completeEmailChange(): Promise<{
57
324
  error: string | null;
58
325
  newEmail: string | null;
59
326
  }>;
60
327
  /**
61
- * Resend confirmation email for signup
62
- * Should be rate-limited on the client side (30 second cooldown)
328
+ * Resend the signup confirmation email for a given address.
329
+ *
330
+ * The caller should enforce a client-side cooldown (recommended: 30 seconds)
331
+ * to prevent abuse, since Supabase may not always rate-limit resends on its
332
+ * own.
333
+ *
334
+ * @param email - The email address that needs a new confirmation link.
335
+ * @returns An object with an `error` field (`null` on success).
336
+ *
337
+ * @example
338
+ * ```ts
339
+ * const { error } = await resendConfirmationEmail('user@example.com');
340
+ * ```
63
341
  */
64
342
  export declare function resendConfirmationEmail(email: string): Promise<{
65
343
  error: string | null;
66
344
  }>;
67
345
  /**
68
- * Verify OTP token (for email confirmation).
69
- * Absorbs confirm page's direct Supabase call.
346
+ * Verify an OTP token hash received from a confirmation email link.
347
+ *
348
+ * This absorbs the direct Supabase call that would otherwise live in the
349
+ * confirm page component, keeping all auth logic centralised in this module.
350
+ *
351
+ * @param tokenHash - The `token_hash` query parameter from the confirmation URL.
352
+ * @param type - The type of OTP: `'signup'`, `'email'`, or `'email_change'`.
353
+ * @returns An object with an `error` field (`null` on success).
354
+ *
355
+ * @example
356
+ * ```ts
357
+ * // On the /confirm page:
358
+ * const hash = new URL(location.href).searchParams.get('token_hash');
359
+ * const { error } = await verifyOtp(hash, 'signup');
360
+ * ```
70
361
  */
71
362
  export declare function verifyOtp(tokenHash: string, type: 'signup' | 'email' | 'email_change'): Promise<{
72
363
  error: string | null;
73
364
  }>;
74
365
  /**
75
- * Get a valid (non-expired) session, or null.
76
- * Merges getSession() + isSessionExpired() into a single call.
366
+ * Get a valid (non-expired) session, or `null`.
367
+ *
368
+ * This is a convenience wrapper that combines {@link getSession} and
369
+ * {@link isSessionExpired} into a single call, useful when the caller only
370
+ * cares about sessions that can still be used for API requests.
371
+ *
372
+ * @returns A non-expired `Session`, or `null`.
373
+ *
374
+ * @example
375
+ * ```ts
376
+ * const session = await getValidSession();
377
+ * if (!session) {
378
+ * redirectToLogin();
379
+ * }
380
+ * ```
381
+ *
382
+ * @see {@link getSession}
383
+ * @see {@link isSessionExpired}
77
384
  */
78
385
  export declare function getValidSession(): Promise<Session | null>;
79
386
  //# sourceMappingURL=auth.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/supabase/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AA8B3D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgEnF;AAED,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,OAAO,CAAC,YAAY,CAAC,CAoBvB;AAED,wBAAsB,OAAO,CAAC,OAAO,CAAC,EAAE;IACtC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CA4DpC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CA0C1D;AA+BD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAMjE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzE;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAoBnC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAmDnC;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,oBAAoB,EAAE,OAAO,CAAA;CAAE,CAAC,CAQlE;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC;IACnD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC,CA4BD;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAU9F;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,cAAc,GACxC,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAOnC;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAK/D"}
1
+ {"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/supabase/auth.ts"],"names":[],"mappings":"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"}