@synqauth/react-native 0.0.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Synq for React Native: sign-in through the system browser, with tokens in the de
 
 Synq is customer identity for businesses: an OpenID Connect issuer for each of your brands, with Solana wallet, social, email and passkey sign-in. The documentation is at [docs.synq.build](https://docs.synq.build).
 
-This package is at 0.x and hasn't been published yet: its API can change in any release until Synq's first customer depends on it.
+This package is at 0.x, so a minor release can change its API: see its CHANGELOG.md.
 
 ## Usage
 
@@ -32,6 +32,8 @@ const { signIn, signOut } = useAuth()
 
 Sign-in opens the system browser (ASWebAuthenticationSession on iOS, Custom Tabs on Android), never an embedded web view. The session, refresh token included, stays in the device's secure storage.
 
+To sign people in on the app's own screens instead (own-UI sign-in, on for the app in the dashboard), use `useSignIn()`: `password.signIn({ email, password })`, `emailCode.send(email)` and `emailCode.verify(code)`, and the rest. Passkeys, and anything else only the hosted page can do, go on in the system browser with `continueInBrowser()`.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AccountClient, AuthorizationUrlOptions, IdTokenClaims, Session, SynqClient, SynqError, SynqStorage } from "@synqauth/js";
+import { AccountClient, AuthorizationUrlOptions, AvatarInfo, AvatarPerson, AvatarStyle, ChallengeMethod, ChallengeProblem, DeniedReason, IdTokenClaims, RedirectReason, Session, StartSignInOptions, SynqClient, SynqError, SynqStorage } from "@synqauth/js";
 import { ReactNode } from "react";
 //#region src/storage.d.ts
 /** The part of `expo-secure-store` the SDK uses: pass the module itself. */
@@ -128,6 +128,26 @@ interface UseUser {
 }
 /** Who is signed in, and their account. */
 export declare function useUser(): UseUser;
+/** What `useAvatar()` answers: what the avatar is drawn from, and Synq's own default as SVG. */
+interface UseAvatar extends AvatarInfo {
+  /**
+   * Synq's own default for them, as SVG markup (`avatarSvg`): draw it with
+   * react-native-svg's `SvgXml`, clipped to a circle, where no picture of
+   * theirs or of the app's own shows.
+   */
+  readonly svg: string;
+}
+/**
+ * What the avatar of `user` is drawn from (AERO-2704): the signed-in person
+ * by default, from their ID token, or anyone as Synq names them (`id` and
+ * `username` from the management API work too). Show `picture` when its
+ * `source` is one the app shows; else the app's own art from `seed`
+ * (`defaultPick` over its set); else `defaultPicture`; else `svg`. Null
+ * while there is nobody.
+ */
+export declare function useAvatar(user?: AvatarPerson | null, options?: {
+  style?: AvatarStyle;
+}): UseAvatar | null;
 /** What `useAuth()` answers: signing in and out, each answering `{ data, error }`. */
 interface UseAuth {
   readonly isLoaded: boolean;
@@ -142,4 +162,79 @@ interface UseAuth {
 /** Signing in and out. */
 export declare function useAuth(): UseAuth;
 //#endregion
-export type { SecureStoreModule, SynqNative, SynqNativeOptions, SynqNativeProviderProps, SynqResult, UseAuth, UseSession, UseUser, WebBrowserModule };
+//#region src/sign-in.d.ts
+/** Where a sign-in is: what the screen 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`), `unavailable` (Synq
+   * couldn't be reached, or failed).
+   */
+  readonly code: ChallengeProblem | 'expired' | 'refused' | '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()` 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: `continueInBrowser()` 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 verifyEmail: {
+    readonly verify: (code: string) => Promise<void>;
+    readonly resend: () => Promise<void>;
+    readonly skip: () => Promise<void>;
+  };
+  /**
+   * Goes on at the hosted page in the system browser, with the method and
+   * address Synq named, or these: a passkey, a token gate, a step-up. A
+   * closed browser is the error `cancelled`.
+   */
+  readonly continueInBrowser: (options?: {
+    method?: string;
+    loginHint?: string;
+  }) => Promise<SynqResult<Session>>;
+  /** Drops the sign-in under way and goes back to the first step. */
+  readonly startOver: () => void;
+}
+/**
+ * One sign-in on the app's own screens. The provider follows the session
+ * it ends with, as after `useAuth().signIn()`.
+ */
+export declare function useSignIn(options?: StartSignInOptions): UseSignIn;
+//#endregion
+export type { SecureStoreModule, SignInHandover, SignInProblem, SignInStep, SynqNative, SynqNativeOptions, SynqNativeProviderProps, SynqResult, UseAuth, UseAvatar, UseSession, UseSignIn, UseUser, WebBrowserModule };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { SynqError, accountApiUrl, createAccountClient, createSynqClient, isSynqError } from "@synqauth/js";
-import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { SynqError, accountApiUrl, avatarOf, avatarSvg, createAccountClient, createSynqClient, isSynqError } from "@synqauth/js";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/storage.ts
 /**
@@ -181,6 +181,7 @@ function SynqNativeProvider({ synq, issuer, children }) {
 		children
 	});
 }
+/** The provider's client and session, for this package's other hooks. */
 function useSynq() {
 	const context = useContext(SynqContext);
 	if (!context) throw new Error("Synq hooks need a <SynqNativeProvider> above them");
@@ -212,6 +213,29 @@ function useUser() {
 		account
 	};
 }
+/**
+* What the avatar of `user` is drawn from (AERO-2704): the signed-in person
+* by default, from their ID token, or anyone as Synq names them (`id` and
+* `username` from the management API work too). Show `picture` when its
+* `source` is one the app shows; else the app's own art from `seed`
+* (`defaultPick` over its set); else `defaultPicture`; else `svg`. Null
+* while there is nobody.
+*/
+function useAvatar(user, options = {}) {
+	const { state } = useSynq();
+	const person = user ?? state.session?.claims ?? null;
+	return useMemo(() => {
+		if (!person) return null;
+		const avatar = avatarOf(person);
+		return {
+			...avatar,
+			svg: avatarSvg(avatar.seed, {
+				style: options.style,
+				initials: avatar.initials
+			})
+		};
+	}, [person, options.style]);
+}
 /** Signing in and out. */
 function useAuth() {
 	const { synq, state } = useSynq();
@@ -249,8 +273,161 @@ function useAuth() {
 		signOut
 	};
 }
+/** Whatever a call threw, as a `SynqError`. */
 function asSynqError(error) {
 	return isSynqError(error) ? error : new SynqError("network_error", String(error), { cause: error });
 }
 //#endregion
-export { CHUNK_SIZE, SynqNativeProvider, createSynqNative, secureStorage, useAuth, useSession, useUser };
+//#region src/sign-in.ts
+/**
+* One sign-in on the app's own screens. The provider follows the session
+* it ends with, as after `useAuth().signIn()`.
+*/
+function useSignIn(options = {}) {
+	const { synq } = useSynq();
+	const auth = useAuth();
+	const flow = useRef(null);
+	const [step, setStep] = useState("start");
+	const [pending, setPending] = useState(0);
+	const [problem, setProblem] = useState(null);
+	const [email, setEmail] = useState(void 0);
+	const [canSkip, setCanSkip] = useState(false);
+	const [handover, setHandover] = useState(null);
+	const start = useRef(options);
+	useEffect(() => {
+		start.current = options;
+	});
+	const actions = useMemo(() => {
+		function show(result) {
+			switch (result.status) {
+				case "signed-in":
+					flow.current = null;
+					setStep("done");
+					setProblem(null);
+					return;
+				case "code-sent":
+					setStep("code");
+					setEmail(result.email);
+					setProblem(null);
+					return;
+				case "verify-email":
+					setStep("verify-email");
+					setEmail(result.email);
+					setCanSkip(result.canSkip);
+					setProblem(null);
+					return;
+				case "retry":
+					setProblem({
+						code: result.problem,
+						message: result.message,
+						...result.retryAfter === void 0 ? {} : { retryAfter: result.retryAfter }
+					});
+					return;
+				case "hosted":
+					setHandover({
+						reason: result.reason,
+						...result.method ? { method: result.method } : {},
+						...result.loginHint ? { loginHint: result.loginHint } : {}
+					});
+					return;
+				case "passkey":
+					setHandover({
+						reason: "passkey_unavailable",
+						method: "passkey"
+					});
+					return;
+				case "refused":
+					flow.current = null;
+					setStep("start");
+					setProblem({
+						code: "refused",
+						reason: result.reason,
+						message: result.message
+					});
+					return;
+			}
+		}
+		async function run(ask) {
+			flow.current ??= synq.client.startSignIn(start.current);
+			const current = flow.current;
+			setPending((n) => n + 1);
+			try {
+				show(await ask(current));
+			} catch (thrown) {
+				const error = asSynqError(thrown);
+				if (error.code === "invalid_session") {
+					flow.current = null;
+					setStep("start");
+					setProblem({
+						code: "expired",
+						message: error.message
+					});
+				} else if (error.code === "too_many_requests") setProblem({
+					code: "limited",
+					message: error.message,
+					...error.retryAfter === void 0 ? {} : { retryAfter: error.retryAfter }
+				});
+				else setProblem({
+					code: "unavailable",
+					message: error.message
+				});
+			} finally {
+				setPending((n) => n - 1);
+			}
+		}
+		return {
+			password: {
+				signIn: (input) => run((f) => f.password.signIn(input)),
+				signUp: (input) => run((f) => f.password.signUp(input))
+			},
+			emailCode: {
+				send: (address) => run((f) => f.email.send(address)),
+				verify: (code) => run((f) => f.email.verify(code)),
+				resend: () => run((f) => f.email.resend())
+			},
+			verifyEmail: {
+				verify: (code) => run((f) => f.verifyEmail.verify(code)),
+				resend: () => run((f) => f.verifyEmail.resend()),
+				skip: () => run((f) => f.verifyEmail.skip())
+			},
+			startOver: () => {
+				flow.current = null;
+				setStep("start");
+				setProblem(null);
+				setEmail(void 0);
+				setCanSkip(false);
+				setHandover(null);
+			}
+		};
+	}, [synq]);
+	const continueInBrowser = useCallback(async (overrides = {}) => {
+		const method = overrides.method ?? handover?.method;
+		const loginHint = overrides.loginHint ?? handover?.loginHint ?? email;
+		const result = await auth.signIn({
+			...method ? { method } : {},
+			...loginHint ? { loginHint } : {}
+		});
+		if (!result.error) {
+			flow.current = null;
+			setHandover(null);
+			setStep("done");
+		}
+		return result;
+	}, [
+		auth,
+		handover,
+		email
+	]);
+	return {
+		step,
+		pending: pending > 0,
+		problem,
+		email,
+		canSkip,
+		handover,
+		...actions,
+		continueInBrowser
+	};
+}
+//#endregion
+export { CHUNK_SIZE, SynqNativeProvider, createSynqNative, secureStorage, useAuth, useAvatar, useSession, useSignIn, useUser };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synqauth/react-native",
-  "version": "0.0.0",
+  "version": "0.3.0",
   "description": "Synq for React Native: sign-in through the system browser, with tokens in the device's secure storage.",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@synqauth/js": "0.0.0"
+    "@synqauth/js": "0.3.0"
   },
   "peerDependencies": {
     "react": ">=19.0.0"