@lumoauth/react 1.5.0 → 1.6.0

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.
package/README.md CHANGED
@@ -364,7 +364,7 @@ return <button onClick={() => signOut()}>Sign out {user!.displayName}</button>;
364
364
  | `getToken()` | `() => Promise<string \| null>` | A valid access token. It refreshes first when needed. |
365
365
  | `handleCallback()` | function | Exchanges the code on the callback page. `<AuthCallback>` calls it for you. |
366
366
  | `sendMagicLink(email, returnTo?, { captchaToken? }?)` | function | Emails a sign-in link. Rejects with a `LumoAuthApiError` when the server refuses the request. |
367
- | `checkEmail(email)` | `(email) => Promise<EmailCheckResult>` | Reports the sign-in methods for an email address |
367
+ | `checkEmail(email)` | `(email) => Promise<EmailCheckResult>` | Reports the sign-in methods that the organization offers. The answer is the same for every address. |
368
368
  | `authStrategy` | `'pkce' \| 'password'` | The strategy in use |
369
369
  | `config` | object | The provider's `domain`, `orgId`, `clientId` and redirect URLs |
370
370
 
@@ -470,19 +470,28 @@ When the server refuses the request, `error` holds the message and `errorCode` t
470
470
 
471
471
  **`useEmailFirst()`** returns `{ checkEmail, isLoading, result, exists, reset }`. Use it to build
472
472
  a sign-in screen that asks for the email address first. `checkEmail(email)` resolves to an
473
- `EmailCheckResult`. It reports whether the account exists and which methods it can use:
474
- `passwordEnabled`, `passkeyEnabled`, `magicLinkEnabled`, `hasPasskey`, `hasPushDevice` and
475
- `maskedEmail`. `exists` is `null` until the first check.
473
+ `EmailCheckResult`. It reports the sign-in methods that the organization offers:
474
+ `passwordEnabled`, `passkeyEnabled` and `magicLinkEnabled`.
475
+
476
+ The answer is the same for every address. It does not say whether the address has an account, so
477
+ a known address and a new one cannot be told apart. Show the same next step to everyone. An
478
+ unknown address fails at that step in the same way as a wrong password. `exists` is `true` when
479
+ the server answered and `false` when the check was not available. It is `null` until the first
480
+ check. `hasPasskey` and `hasPushDevice` are always `false`.
481
+
482
+ The request names your application and sends no cookie. The origin of your app must be one of
483
+ the allowed origins of the application.
476
484
 
477
485
  ```tsx
478
486
  const { checkEmail, isLoading } = useEmailFirst();
479
487
 
480
488
  async function onSubmit(e: React.FormEvent) {
481
489
  e.preventDefault();
482
- const found = await checkEmail(email);
483
- if (!found.exists) return showSignUp();
484
- if (found.magicLinkEnabled) return showMagicLinkOption();
485
- signIn(); // fall back to the LumoAuth sign-in page
490
+ const methods = await checkEmail(email);
491
+ if (!methods.exists) return signIn(); // check not available: the LumoAuth sign-in page
492
+ if (methods.magicLinkEnabled) return showMagicLinkOption();
493
+ if (methods.passwordEnabled) return showPasswordStep();
494
+ signIn();
486
495
  }
487
496
  ```
488
497
 
package/dist/index.d.mts CHANGED
@@ -276,18 +276,22 @@ interface UseMagicLinkReturn {
276
276
  */
277
277
  interface UseEmailFirstReturn {
278
278
  /**
279
- * Discover which sign-in methods this identifier can actually use.
279
+ * Ask which sign-in methods the organization offers (password, passkey,
280
+ * magic link), so that a sign-in card can show the next step.
280
281
  *
281
- * Returns the organization's enabled methods AND what this user has
282
- * enrolled (passkey, push device, magic link, password), so a sign-in card
283
- * can render only the options that will work.
282
+ * The answer is the same for every address and says nothing about the
283
+ * account behind it.
284
284
  */
285
285
  checkEmail: (email: string) => Promise<EmailCheckResult>;
286
286
  /** True while the check is in-flight */
287
287
  isLoading: boolean;
288
288
  /** Full result of the last check, or null if not yet checked */
289
289
  result: EmailCheckResult | null;
290
- /** Shorthand for `result?.exists`, or null if not yet checked */
290
+ /**
291
+ * Shorthand for `result?.exists`, or null if not yet checked. `true`
292
+ * means that the server answered, not that the address has an account;
293
+ * `false` means that the check was not available.
294
+ */
291
295
  exists: boolean | null;
292
296
  /** Reset state back to idle */
293
297
  reset: () => void;
@@ -701,20 +705,23 @@ declare function useMagicLink(): UseMagicLinkReturn;
701
705
  /**
702
706
  * Hook for email-first login flows.
703
707
  *
704
- * Checks whether an account exists for the given email before showing
705
- * the password or magic-link step.
708
+ * Asks which sign-in methods the organization offers, so that your form can
709
+ * show the next step after an address was typed. The answer is the same for
710
+ * every address: it does not say whether the address has an account, so do
711
+ * not branch on "known user" versus "new user". `exists` is `true` whenever
712
+ * the server answered, and `false` only when the check was not available.
706
713
  *
707
714
  * @example
708
715
  * ```tsx
709
- * const { checkEmail, isLoading, exists, reset } = useEmailFirst();
716
+ * const { checkEmail, isLoading, reset } = useEmailFirst();
717
+ * const { signIn } = useAuth();
710
718
  *
711
719
  * async function handleEmailSubmit(email: string) {
712
- * const found = await checkEmail(email);
713
- * if (found) {
714
- * // show password / magic-link step
715
- * } else {
716
- * // show "no account found" or sign-up prompt
717
- * }
720
+ * const methods = await checkEmail(email);
721
+ * if (!methods.exists) return signIn(); // check not available: hosted login page
722
+ * if (methods.magicLinkEnabled) return showMagicLinkOption();
723
+ * if (methods.passwordEnabled) return showPasswordStep();
724
+ * signIn();
718
725
  * }
719
726
  * ```
720
727
  */
package/dist/index.d.ts CHANGED
@@ -276,18 +276,22 @@ interface UseMagicLinkReturn {
276
276
  */
277
277
  interface UseEmailFirstReturn {
278
278
  /**
279
- * Discover which sign-in methods this identifier can actually use.
279
+ * Ask which sign-in methods the organization offers (password, passkey,
280
+ * magic link), so that a sign-in card can show the next step.
280
281
  *
281
- * Returns the organization's enabled methods AND what this user has
282
- * enrolled (passkey, push device, magic link, password), so a sign-in card
283
- * can render only the options that will work.
282
+ * The answer is the same for every address and says nothing about the
283
+ * account behind it.
284
284
  */
285
285
  checkEmail: (email: string) => Promise<EmailCheckResult>;
286
286
  /** True while the check is in-flight */
287
287
  isLoading: boolean;
288
288
  /** Full result of the last check, or null if not yet checked */
289
289
  result: EmailCheckResult | null;
290
- /** Shorthand for `result?.exists`, or null if not yet checked */
290
+ /**
291
+ * Shorthand for `result?.exists`, or null if not yet checked. `true`
292
+ * means that the server answered, not that the address has an account;
293
+ * `false` means that the check was not available.
294
+ */
291
295
  exists: boolean | null;
292
296
  /** Reset state back to idle */
293
297
  reset: () => void;
@@ -701,20 +705,23 @@ declare function useMagicLink(): UseMagicLinkReturn;
701
705
  /**
702
706
  * Hook for email-first login flows.
703
707
  *
704
- * Checks whether an account exists for the given email before showing
705
- * the password or magic-link step.
708
+ * Asks which sign-in methods the organization offers, so that your form can
709
+ * show the next step after an address was typed. The answer is the same for
710
+ * every address: it does not say whether the address has an account, so do
711
+ * not branch on "known user" versus "new user". `exists` is `true` whenever
712
+ * the server answered, and `false` only when the check was not available.
706
713
  *
707
714
  * @example
708
715
  * ```tsx
709
- * const { checkEmail, isLoading, exists, reset } = useEmailFirst();
716
+ * const { checkEmail, isLoading, reset } = useEmailFirst();
717
+ * const { signIn } = useAuth();
710
718
  *
711
719
  * async function handleEmailSubmit(email: string) {
712
- * const found = await checkEmail(email);
713
- * if (found) {
714
- * // show password / magic-link step
715
- * } else {
716
- * // show "no account found" or sign-up prompt
717
- * }
720
+ * const methods = await checkEmail(email);
721
+ * if (!methods.exists) return signIn(); // check not available: hosted login page
722
+ * if (methods.magicLinkEnabled) return showMagicLinkOption();
723
+ * if (methods.passwordEnabled) return showPasswordStep();
724
+ * signIn();
718
725
  * }
719
726
  * ```
720
727
  */