@synqauth/react 0.0.0 → 0.2.0

package/README.md

@@ -36,7 +36,9 @@ export default function Settings() {
 }
 ```
 
-The hooks are `useSession()`, `useUser()`, `useWallets()`, `useLinkedAccounts()`, `useAccountSessions()` and `useAuth()`. Every call answers `{ data, error }` and never throws, and a change clicked twice while it's under way is sent once.
+To sign people in on your own page (own-UI sign-in, on for the app in the dashboard), render `<SignInForm returnTo="/dashboard" />`, lay out its parts (`PasskeyButton`, `PasswordForm`, `EmailCodeForm`, `VerifyEmailForm`) your own way, or build your own form on `useSignIn()`. It offers a passkey where the browser can use the brand's on your page (Chrome and Edge 128+, Safari 18+, Firefox 152+), then an emailed code or a password. Anything only Synq's hosted page can do, such as a token gate, goes there.
+
+The hooks are `useSession()`, `useSignIn()`, `useUser()`, `useWallets()`, `useLinkedAccounts()`, `useAccountSessions()` and `useAuth()`. Every call answers `{ data, error }` and never throws, and a change clicked twice while it's under way is sent once.
 
 The components take Synq's look from `@synqauth/react/styles.css`, themed with CSS variables (`--synq-color-primary`, `--synq-radius`...), or none with `unstyled`. `<SynqProvider messages>` puts their words in your app's language.
 

package/dist/index.d.ts

@@ -1,6 +1,99 @@
 
-import { ReactNode } from "react";
-import { AccountComponents, SynqError } from "@synqauth/js";
+import { InputHTMLAttributes, ReactNode } from "react";
+import { AccountComponents, ChallengeMethod, ChallengeProblem, DeniedReason, RedirectReason, SynqError } from "@synqauth/js";
+//#region src/sign-in.d.ts
+/** Where a sign-in is: what the form shows. */
+type SignInStep = 'start' | 'code' | 'verify-email' | 'done';
+/** What went wrong with the last step: branch on `code`, never on the English. */
+interface SignInProblem {
+  /**
+   * Synq's problem with the step (`wrong_credentials`, `wrong_code`…), or
+   * the sign-in's own: `expired` (it timed out: start again), `refused`
+   * (this person can't sign in here: see `reason`), `passkey_cancelled`
+   * (the browser's passkey prompt closed with none), `unavailable` (the
+   * app's server couldn't be reached, or failed).
+   */
+  readonly code: ChallengeProblem | 'expired' | 'refused' | 'passkey_cancelled' | 'unavailable';
+  /** Why, when `refused`. */
+  readonly reason?: DeniedReason;
+  /** Synq's words for it, in English: show your own for `code` in another language. */
+  readonly message: string;
+  /** Seconds to wait first, when Synq said. */
+  readonly retryAfter?: number;
+}
+/** What only the hosted page can do for this sign-in, and what to take there. */
+interface SignInHandover {
+  readonly reason: RedirectReason;
+  readonly method?: ChallengeMethod;
+  readonly loginHint?: string;
+}
+/** What `useSignIn()` takes: where to go once signed in, or what to do instead. */
+interface UseSignInOptions {
+  /** Where to go once signed in: the page it started on by default. */
+  readonly returnTo?: string;
+  /** Called once signed in, with where to go, instead of going there. */
+  readonly onSignedIn?: (returnTo: string) => void;
+}
+/** What `useSignIn()` answers: the sign-in's step, what went wrong, and each method's steps. */
+interface UseSignIn {
+  readonly step: SignInStep;
+  /** Whether a step is on its way to Synq. */
+  readonly pending: boolean;
+  readonly problem: SignInProblem | null;
+  /** The address a code went to. */
+  readonly email: string | undefined;
+  /** Whether a new account's address may be left unverified for now. */
+  readonly canSkip: boolean;
+  /** Set when only the hosted page can go on: `continueOnHostedPage()` goes there. */
+  readonly handover: SignInHandover | null;
+  readonly password: {
+    readonly signIn: (input: {
+      email: string;
+      password: string;
+    }) => Promise<void>;
+    readonly signUp: (input: {
+      email: string;
+      password: string;
+    }) => Promise<void>;
+  };
+  readonly emailCode: {
+    readonly send: (email: string) => Promise<void>;
+    readonly verify: (code: string) => Promise<void>;
+    readonly resend: () => Promise<void>;
+  };
+  readonly passkey: {
+    /** Whether this browser takes the issuer's passkeys on this page (related origins). */
+    readonly supported: boolean;
+    /** Whether it offers them in the address field as the person types (conditional UI). */
+    readonly autofill: boolean;
+    /**
+     * On a brand's custom domain, the brand's own Synq host, whose passkeys
+     * work too (`signIn({ related: true })`): known after the first passkey
+     * prompt.
+     */
+    readonly relatedDomain: string | null;
+    readonly signIn: (options?: {
+      related?: boolean;
+    }) => Promise<void>;
+    /** Offers passkeys in the address field (`autocomplete="username webauthn"`): call once it's on the page. */
+    readonly startAutofill: () => Promise<void>;
+  };
+  readonly verifyEmail: {
+    readonly verify: (code: string) => Promise<void>;
+    readonly resend: () => Promise<void>;
+    readonly skip: () => Promise<void>;
+  };
+  /** Goes on at the hosted page, with the method and address Synq named, or these. */
+  readonly continueOnHostedPage: (options?: {
+    method?: ChallengeMethod;
+    loginHint?: string;
+  }) => void;
+  /** Drops the sign-in under way and goes back to the first step. */
+  readonly startOver: () => Promise<void>;
+}
+/** One sign-in on the app's own screens, through the route mount's `sign-in/flow`. */
+export declare function useSignIn(options?: UseSignInOptions): UseSignIn;
+//#endregion
 //#region src/messages.d.ts
 /** Every word the components show, for `<SynqProvider messages>`; any left out stay English. */
 interface SynqMessages {
@@ -40,6 +133,66 @@ interface SynqMessages {
   readonly makeWalletPrimary: (name: string) => string;
   /** The label of the field naming a wallet. */
   readonly walletName: (address: string) => string;
+  /** API keys for the brand's APIs (AERO-1693). */
+  readonly apiKeys: string;
+  readonly noApiKeys: string;
+  readonly newApiKey: string;
+  /** The field picking which of the brand's APIs a key is for. */
+  readonly api: string;
+  /** The scopes a key may use. */
+  readonly keyScopes: string;
+  readonly expires: string;
+  readonly never: string;
+  readonly inDays: (days: number) => string;
+  readonly makeKey: string;
+  readonly makingKey: string;
+  readonly revoke: string;
+  /** The label of the button that revokes a key. */
+  readonly revokeKey: (name: string) => string;
+  readonly revoked: string;
+  readonly expired: string;
+  readonly lastUsed: (when: string) => string;
+  readonly neverUsed: string;
+  readonly expiresOn: (when: string) => string;
+  /** Over the key just made, the only time it shows. */
+  readonly copyKeyNow: string;
+  readonly copy: string;
+  readonly copied: string;
+  readonly done: string;
+  /** When making a key needs a sign-in from the last few minutes. */
+  readonly keyNeedsFreshSignIn: string;
+  readonly signInAgain: string;
+  /** `<SignInForm>` (AERO-1411): sign-in on the app's own screens. */
+  readonly email: string;
+  readonly password: string;
+  readonly signInWithPasskey: string;
+  /** The button for a passkey made at the brand's own Synq host, on its custom domain. */
+  readonly passkeyFor: (domain: string) => string;
+  readonly emailMeACode: string;
+  /** Between a passkey and the other ways. */
+  readonly or: string;
+  readonly code: string;
+  readonly codeSentTo: (email: string) => string;
+  /** Over the code that proves a new account's address. */
+  readonly verifyYourEmail: (email: string) => string;
+  readonly verify: string;
+  readonly sendAnotherCode: string;
+  readonly useAnotherWay: string;
+  readonly skipForNow: string;
+  /** The link to the hosted page's password step, where resetting one lives. */
+  readonly forgotPassword: string;
+  readonly createAccount: string;
+  /** Before the link to the sign-up screen. */
+  readonly newHere: string;
+  /** Before the link back to the sign-in screen. */
+  readonly haveAnAccount: string;
+  /** While the browser goes to the hosted page for what only it can do. */
+  readonly continuingToSignIn: string;
+  readonly tryAgainIn: (seconds: number) => string;
+  /** What went wrong with a step, by `SignInProblem.code`; Synq's English for any left out. */
+  readonly signInProblems: Readonly<Partial<Record<SignInProblem['code'], string>>>;
+  /** Why this person can't sign in here, by `SignInProblem.reason`. */
+  readonly signInRefusals: Readonly<Partial<Record<DeniedReason, string>>>;
 }
 /** The components' English words, which an app's own messages override one by one. */
 export declare const DEFAULT_MESSAGES: SynqMessages;
@@ -136,6 +289,14 @@ type Wallet = AccountComponents['schemas']['Wallet'];
 type LinkedAccount = AccountComponents['schemas']['Identity'];
 /** One of the person's sessions at the brand, on some device. */
 type AccountSession = AccountComponents['schemas']['Session'];
+/** One of the person's API keys for the brand's APIs (AERO-1693): never the key itself. */
+type ApiKey = AccountComponents['schemas']['UserApiKey'];
+/** A key just made: `key` is the key itself, in this answer only. */
+type NewApiKey = AccountComponents['schemas']['NewUserApiKey'];
+/** What making an API key takes: the API's identifier, a name, its scopes, an expiry if any. */
+type ApiKeyInput = AccountComponents['schemas']['UserApiKeyCreate'];
+/** One of the brand's APIs the person may make keys for, with the scopes it defines. */
+type KeyableApi = AccountComponents['schemas']['KeyableApi'];
 //#endregion
 //#region src/mount.d.ts
 /** Calls the app's route mount: `request('session')`, `request('account/v1/profile', { method: 'PATCH', ... })`. */
@@ -217,6 +378,10 @@ export declare function useWallets(): UseAccountData<readonly Wallet[]>;
 export declare function useLinkedAccounts(): UseAccountData<readonly LinkedAccount[]>;
 /** The person's sessions at the brand, on every device. */
 export declare function useAccountSessions(): UseAccountData<readonly AccountSession[]>;
+/** The person's API keys for the brand's APIs (AERO-1693), revoked and expired ones too. */
+export declare function useApiKeys(): UseAccountData<readonly ApiKey[]>;
+/** The brand's APIs that let the person make keys, with the scopes each defines. */
+export declare function useKeyableApis(): UseAccountData<readonly KeyableApi[]>;
 /** What `useUser()` answers: the person's claims, profile and metadata, and `update` for the profile. */
 interface UseUser {
   readonly isLoaded: boolean;
@@ -274,6 +439,18 @@ interface UseAuth {
     /** Signs that device out. */
     readonly end: (id: string) => Promise<SynqResult<null>>;
   };
+  /** Their API keys for the brand's own APIs (AERO-1693). */
+  readonly apiKeys: {
+    readonly list: () => Promise<SynqResult<readonly ApiKey[]>>;
+    /**
+     * Makes a key: its `key` is in this answer only, so show it once. Making
+     * one needs a sign-in from the last 5 minutes (`fresh_sign_in_required`:
+     * `signIn({ maxAge: 300 })`).
+     */
+    readonly create: (input: ApiKeyInput) => Promise<SynqResult<NewApiKey>>;
+    /** Revokes a key at once. */
+    readonly revoke: (id: string) => Promise<SynqResult<null>>;
+  };
   /** Each browser plugin's actions, by its id (`usePlugin` types them). */
   readonly plugins: Readonly<Record<string, unknown>>;
 }
@@ -310,6 +487,56 @@ interface SignInButtonProps extends SignInOptions, SynqStyleProps {
 /** A button that sends the browser to sign in, through the app's route mount. */
 export declare function SignInButton({ unstyled, className, children, ...options }: SignInButtonProps): ReactNode;
 //#endregion
+//#region src/components/SignInForm.d.ts
+/** What `SignInForm` takes: which ways to offer, where it starts, and its look. */
+interface SignInFormProps extends UseSignInOptions, SynqStyleProps {
+  /** The ways to offer, of those the app has on: all three by default. */
+  readonly methods?: readonly ChallengeMethod[];
+  /** Which screen it opens on. People can switch, where passwords are on. */
+  readonly screen?: 'sign-in' | 'sign-up';
+}
+/** What each part of the form takes: the sign-in it works on, and its look. */
+interface SignInPartProps extends SynqStyleProps {
+  /** The sign-in, from `useSignIn()`. */
+  readonly signIn: UseSignIn;
+}
+/**
+ * Sign-in on the app's own page: a passkey where the browser takes the
+ * issuer's, then an emailed code or a password, and the code or the new
+ * address's proof after. Whatever only the hosted page can do, it goes
+ * there for.
+ */
+export declare function SignInForm({ methods, screen: initialScreen, returnTo, onSignedIn, unstyled, className }: SignInFormProps): ReactNode;
+/** The button for a passkey: the brand's, or with `related` its own host's on its custom domain. */
+export declare function PasskeyButton({ signIn, related, children, unstyled, className }: SignInPartProps & {
+  readonly related?: boolean;
+  readonly children?: ReactNode;
+}): ReactNode;
+/**
+ * An email address and a password: signs in, or with `screen="sign-up"`
+ * makes an account. With `emailCode`, it offers a code by email for the
+ * same address too.
+ */
+export declare function PasswordForm({ signIn, screen, emailCode, autofill, unstyled, className }: SignInPartProps & {
+  readonly screen?: 'sign-in' | 'sign-up';
+  readonly emailCode?: boolean;
+  /** Offer passkeys in the address field as the person types, where the browser can. */
+  readonly autofill?: boolean;
+}): ReactNode;
+/** An emailed code: the address to send it to, then the code it held. */
+export declare function EmailCodeForm({ signIn, autofill, unstyled, className }: SignInPartProps & {
+  /** Offer passkeys in the address field as the person types, where the browser can. */
+  readonly autofill?: boolean;
+}): ReactNode;
+/** The code that proves a new account's address, or "Skip for now" where the brand allows. */
+export declare function VerifyEmailForm({ signIn, unstyled, className }: SignInPartProps): ReactNode;
+/** What `OneTimeCodeInput` takes: its label, its look, and any input attribute. */
+interface OneTimeCodeInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'className'>, SynqStyleProps {
+  readonly label: ReactNode;
+}
+/** The field for an emailed code, named `code`: digits, filled from the message where the device can. */
+export declare function OneTimeCodeInput({ label, unstyled, className, ...input }: OneTimeCodeInputProps): ReactNode;
+//#endregion
 //#region src/components/UserButton.d.ts
 /** What `UserButton` takes: where its account link goes, and its look. */
 interface UserButtonProps extends SynqStyleProps {
@@ -325,11 +552,15 @@ interface UserButtonProps extends SynqStyleProps {
 export declare function UserButton({ unstyled, className, accountHref }: UserButtonProps): ReactNode;
 //#endregion
 //#region src/components/AccountManager.d.ts
-/** One part of `AccountManager`: the profile, the ways to sign in, or the sessions. */
-type AccountSection = 'profile' | 'accounts' | 'sessions';
+/** One part of `AccountManager`: the profile, the ways to sign in, the sessions, or the API keys. */
+type AccountSection = 'profile' | 'accounts' | 'sessions' | 'apiKeys';
 /** What `AccountManager` takes: which sections it shows, and its look. */
 interface AccountManagerProps extends SynqStyleProps {
-  /** The parts it shows, in this order: all three by default. */
+  /**
+   * The parts it shows, in this order: all four by default. The API keys
+   * show only where one of the brand's APIs lets people make keys, or the
+   * person has some.
+   */
   readonly sections?: readonly AccountSection[];
 }
 /** Manage the signed-in person's account. Nothing while nobody is signed in. */
@@ -341,4 +572,4 @@ type WalletManagerProps = SynqStyleProps;
 /** Manage the signed-in person's wallets. Nothing while nobody is signed in. */
 export declare function WalletManager({ unstyled, className }: WalletManagerProps): ReactNode;
 //#endregion
-export type { AccountManagerProps, AccountSection, AccountSession, LinkedAccount, Profile, ProfileUpdate, SessionStatus, SignInButtonProps, SignInMethod, SignInMethods, SignInOptions, SynqClientPlugin, SynqMessages, SynqMountRequest, SynqProviderProps, SynqResult, SynqSessionInfo, SynqStyleProps, SynqUser, UseAccountData, UseAuth, UseSession, UseUser, UserButtonProps, UserMetadata, Wallet, WalletManagerProps };
+export type { AccountManagerProps, AccountSection, AccountSession, ApiKey, ApiKeyInput, KeyableApi, LinkedAccount, NewApiKey, OneTimeCodeInputProps, Profile, ProfileUpdate, SessionStatus, SignInButtonProps, SignInFormProps, SignInHandover, SignInMethod, SignInMethods, SignInOptions, SignInPartProps, SignInProblem, SignInStep, SynqClientPlugin, SynqMessages, SynqMountRequest, SynqProviderProps, SynqResult, SynqSessionInfo, SynqStyleProps, SynqUser, UseAccountData, UseAuth, UseSession, UseSignIn, UseSignInOptions, UseUser, UserButtonProps, UserMetadata, Wallet, WalletManagerProps };