@synqauth/react 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aerosol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @synqauth/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React hooks and components for Synq.
+
+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.
+
+## Quick start
+
+`@synqauth/react` talks to your app's own route mount, which `@synqauth/nextjs` serves, so the browser never holds a Synq token. Set that up first (its README), then give the pages that need the session a provider, in a route group's layout so the rest of the app (marketing pages, say) stays static:
+
+```tsx
+// app/(app)/layout.tsx
+import { SynqProvider } from '@synqauth/react'
+import { synq } from '@/lib/synq'
+
+export default async function AppLayout({ children }: { children: React.ReactNode }) {
+  return <SynqProvider initialSession={await synq.getSession()}>{children}</SynqProvider>
+}
+```
+
+```tsx
+// app/(app)/settings/page.tsx
+import '@synqauth/react/styles.css'
+import { AccountManager, UserButton, WalletManager } from '@synqauth/react'
+
+export default function Settings() {
+  return (
+    <>
+      <UserButton accountHref="/settings" />
+      <AccountManager />
+      <WalletManager />
+    </>
+  )
+}
+```
+
+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.
+
+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.
+
+Plugins hold functions, which a server component can't pass: an app with plugins wraps `SynqProvider` in a client component of its own.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,344 @@
+
+import { ReactNode } from "react";
+import { AccountComponents, SynqError } from "@synqauth/js";
+//#region src/messages.d.ts
+/** Every word the components show, for `<SynqProvider messages>`; any left out stay English. */
+interface SynqMessages {
+  readonly signIn: string;
+  readonly signOut: string;
+  readonly manageAccount: string;
+  /** What to call someone with no name, username or email address. */
+  readonly account: string;
+  readonly loading: string;
+  readonly save: string;
+  readonly saving: string;
+  readonly saved: string;
+  readonly cancel: string;
+  readonly profile: string;
+  readonly name: string;
+  readonly username: string;
+  readonly waysToSignIn: string;
+  readonly remove: string;
+  /** The label of the button that stops a way signing them in. */
+  readonly removeAccount: (provider: string, subject: string) => string;
+  /** What each way to sign in is called, by provider: `email`, `solana`, `google`... */
+  readonly providers: Readonly<Record<string, string>>;
+  readonly devices: string;
+  /** A session whose sign-in time Synq didn't keep. */
+  readonly signedIn: string;
+  /** The mark on the session this page is signed in with (`current`). */
+  readonly thisDevice: string;
+  /** The label of the button that signs a device out. */
+  readonly signOutDevice: (when: string) => string;
+  readonly apps: (count: number) => string;
+  readonly wallets: string;
+  readonly noWallets: string;
+  readonly primary: string;
+  readonly rename: string;
+  readonly renameWallet: (name: string) => string;
+  readonly makePrimary: string;
+  readonly makeWalletPrimary: (name: string) => string;
+  /** The label of the field naming a wallet. */
+  readonly walletName: (address: string) => string;
+}
+/** The components' English words, which an app's own messages override one by one. */
+export declare const DEFAULT_MESSAGES: SynqMessages;
+//#endregion
+//#region src/types.d.ts
+/** A call's outcome: its data, or the `SynqError` it failed with (branch on `error.code`). */
+type SynqResult<T> = {
+  readonly data: T;
+  readonly error: null;
+} | {
+  readonly data: null;
+  readonly error: SynqError;
+};
+/** A signed-in person, from the ID token Synq issued at sign-in. */
+interface SynqUser {
+  /** The user's id at the brand (`usr_…`). */
+  readonly sub: string;
+  readonly email?: string;
+  readonly email_verified?: boolean;
+  readonly name?: string;
+  readonly preferred_username?: string;
+  readonly picture?: string;
+  /** When they signed in, in seconds since the epoch. */
+  readonly auth_time?: number;
+  /** How they signed in: `pwd`, `otp`, `wallet`, `hwk`, `fed`... */
+  readonly amr?: readonly string[];
+  readonly [claim: string]: unknown;
+}
+/** Who is signed in, as the app's server tells the browser: `await synq.getSession()`, or the route mount's `session`. */
+interface SynqSessionInfo {
+  readonly user: SynqUser | null;
+  /** When the session's main access token expires, in seconds since the epoch. */
+  readonly expiresAt: number | null;
+}
+/**
+ * What the brand keeps for the person (the account API's `metadata`).
+ * Augment it to type what the app reads:
+ *
+ * ```ts
+ * declare module '@synqauth/react' {
+ *   interface UserMetadata {
+ *     plan?: 'free' | 'pro'
+ *   }
+ * }
+ * ```
+ */
+interface UserMetadata {
+  readonly [field: string]: unknown;
+}
+/**
+ * The ways a brand signs people in, as `synq_method` names them: the hosted
+ * page goes straight to one. A brand's own connection joins them the same way:
+ *
+ * ```ts
+ * declare module '@synqauth/react' {
+ *   interface SignInMethods {
+ *     okta: true
+ *   }
+ * }
+ * ```
+ */
+interface SignInMethods {
+  readonly password: true;
+  readonly email: true;
+  readonly passkey: true;
+  readonly wallet: true;
+  readonly google: true;
+  readonly microsoft: true;
+  readonly discord: true;
+}
+/** One of the brand's sign-in methods. */
+type SignInMethod = Extract<keyof SignInMethods, string>;
+/** How to send the person to sign in. */
+interface SignInOptions {
+  /** Where to come back to: a path on the app, the current page by default. */
+  readonly returnTo?: string;
+  /** Go straight to one sign-in method. */
+  readonly method?: SignInMethod;
+  /** Fills in their email address. */
+  readonly loginHint?: string;
+  readonly prompt?: 'login' | 'none' | 'consent' | 'select_account';
+  /** Ask them to sign in again when their last sign-in is older than this many seconds. */
+  readonly maxAge?: number;
+  /** Offer a new passkey once they've signed in again. */
+  readonly intent?: 'add-passkey';
+}
+/** The person's profile at the brand. */
+type Profile = AccountComponents['schemas']['Profile'];
+/** Changes to it: only the fields given change, and `null` clears one. */
+type ProfileUpdate = AccountComponents['schemas']['ProfileUpdate'];
+/** A Solana wallet the person signs in with. */
+type Wallet = AccountComponents['schemas']['Wallet'];
+/** A way the person signs in: their email address, a wallet, a Google account... */
+type LinkedAccount = AccountComponents['schemas']['Identity'];
+/** One of the person's sessions at the brand, on some device. */
+type AccountSession = AccountComponents['schemas']['Session'];
+//#endregion
+//#region src/mount.d.ts
+/** Calls the app's route mount: `request('session')`, `request('account/v1/profile', { method: 'PATCH', ... })`. */
+type SynqMountRequest = (path: string, init?: RequestInit) => Promise<Response>;
+/**
+ * A browser plugin: actions over its server plugin's routes. The same shape
+ * as `@synqauth/nextjs/client`'s `defineSynqClientPlugin`, so its plugins
+ * work here as they are.
+ */
+interface SynqClientPlugin<Id extends string = string, Actions = unknown> {
+  readonly id: Id;
+  actions(request: SynqMountRequest): Actions;
+}
+//#endregion
+//#region src/store.d.ts
+/** `error` when the app couldn't be asked who is signed in, and nothing is known yet: the provider asks again, waiting longer each time. */
+type SessionStatus = 'loading' | 'signed-in' | 'signed-out' | 'error';
+//#endregion
+//#region src/provider.d.ts
+/** What `SynqProvider` takes: the server's session, the route mount, the words and the plugins. */
+interface SynqProviderProps {
+  /**
+   * Who is signed in, from the server: `await synq.getSession()` in a layout.
+   * With it the first render needs no request; without it the provider asks
+   * the route mount once it mounts.
+   */
+  readonly initialSession?: SynqSessionInfo | null;
+  /** The route mount: `/api/auth` by default. */
+  readonly basePath?: string;
+  /**
+   * Browser plugins (`defineSynqClientPlugin`), their actions on
+   * `useAuth().plugins` and `usePlugin()`. Plugins hold functions, so a
+   * server component can't pass them: wrap the provider in a client
+   * component of the app's own.
+   */
+  readonly plugins?: readonly SynqClientPlugin[];
+  /** How to reach the mount: the browser's `fetch` by default. */
+  readonly fetch?: typeof fetch;
+  /** How to go to sign-in and sign-out pages: `location.assign` by default. */
+  readonly navigate?: (url: string) => void;
+  /** The components' words, in the app's language: any left out are English. */
+  readonly messages?: Partial<SynqMessages>;
+  readonly children?: ReactNode;
+}
+/** Synq for the components under it. Its route mount and `fetch` are read once, when it mounts. */
+export declare function SynqProvider({ initialSession, basePath, plugins, fetch: fetcher, navigate, messages, children }: SynqProviderProps): ReactNode;
+/** A browser plugin's actions, typed by the plugin, which must be one of the provider's `plugins`. */
+export declare function usePlugin<Actions>(plugin: SynqClientPlugin<string, Actions>): Actions;
+//#endregion
+//#region src/hooks.d.ts
+/** What `useSession()` answers: who is signed in, and whether the app said yet. */
+interface UseSession {
+  /** `loading` until the app says who is signed in; never with `initialSession`. */
+  readonly status: SessionStatus;
+  readonly isLoaded: boolean;
+  readonly isSignedIn: boolean;
+  readonly user: SynqUser | null;
+  /** When the session's main access token expires; the app's server refreshes it. */
+  readonly expiresAt: number | null;
+  /** Why the app couldn't say who is signed in, the last time it was asked. */
+  readonly error: SynqError | null;
+  /** Asks the app again. */
+  readonly refresh: () => Promise<void>;
+}
+/** Who is signed in. It reads the session alone, and asks the account API nothing. */
+export declare function useSession(): UseSession;
+/** What the account hooks (`useWallets`, `useLinkedAccounts`, `useAccountSessions`) answer: the data, the error, and whether it loaded. */
+interface UseAccountData<T> {
+  readonly data: T | null;
+  readonly error: SynqError | null;
+  /** While it is read, or about to be: someone is signed in and nothing has come back yet. */
+  readonly isLoading: boolean;
+  /** Reads it again. */
+  readonly reload: () => Promise<void>;
+}
+/** The person's wallets, the primary one marked. */
+export declare function useWallets(): UseAccountData<readonly Wallet[]>;
+/** The ways the person signs in: their email address, wallets, social accounts. */
+export declare function useLinkedAccounts(): UseAccountData<readonly LinkedAccount[]>;
+/** The person's sessions at the brand, on every device. */
+export declare function useAccountSessions(): UseAccountData<readonly AccountSession[]>;
+/** What `useUser()` answers: the person's claims, profile and metadata, and `update` for the profile. */
+interface UseUser {
+  readonly isLoaded: boolean;
+  readonly isSignedIn: boolean;
+  /** Who they are, from the ID token: there at once. */
+  readonly user: SynqUser | null;
+  /** Their profile at the brand, read from the account API. */
+  readonly profile: Profile | null;
+  /** What the brand keeps for them: `UserMetadata`, augmented by the app. */
+  readonly metadata: UserMetadata | null;
+  readonly isLoading: boolean;
+  readonly error: SynqError | null;
+  /** Changes their profile: only the fields given, `null` clearing one. */
+  readonly update: (changes: ProfileUpdate) => Promise<SynqResult<Profile>>;
+  /** Reads the profile and metadata again. */
+  readonly reload: () => Promise<void>;
+}
+/** The signed-in person: their ID token's claims at once, then their profile and metadata. */
+export declare function useUser(): UseUser;
+/** What `useAuth()` answers: `signIn`, `signOut`, `link`, and the account's wallets, ways to sign in and sessions. */
+interface UseAuth {
+  readonly isLoaded: boolean;
+  readonly isSignedIn: boolean;
+  readonly userId: string | null;
+  /** Sends the browser to sign in, coming back to `returnTo` (this page by default). */
+  readonly signIn: (options?: SignInOptions) => void;
+  /** Where `signIn` sends the browser: the route mount's `sign-in`. */
+  readonly signInUrl: (options?: SignInOptions) => string;
+  /** Ends the session in the app and at the brand, then goes where the brand sends the browser. */
+  readonly signOut: () => Promise<SynqResult<null>>;
+  /**
+   * Adds a way to sign in to the person's account: Synq asks them to sign in
+   * again, then for `method`, and the browser comes back to `returnTo` (this
+   * page by default). Answers only when it can't start: the method isn't
+   * offered, or they have as many ways in as one may.
+   */
+  readonly link: (method: SignInMethod, options?: {
+    returnTo?: string;
+  }) => Promise<SynqResult<null>>;
+  readonly wallets: {
+    readonly list: () => Promise<SynqResult<readonly Wallet[]>>;
+    /** Names a wallet; `null` takes its name away. */
+    readonly rename: (id: string, label: string | null) => Promise<SynqResult<Wallet>>;
+    /** Makes it their primary wallet, in place of the one that was. */
+    readonly setPrimary: (id: string) => Promise<SynqResult<Wallet>>;
+  };
+  /** The ways they sign in. */
+  readonly accounts: {
+    readonly list: () => Promise<SynqResult<readonly LinkedAccount[]>>;
+    /** Stops a way signing them in. */
+    readonly unlink: (id: string) => Promise<SynqResult<null>>;
+  };
+  readonly sessions: {
+    readonly list: () => Promise<SynqResult<readonly AccountSession[]>>;
+    /** Signs that device out. */
+    readonly end: (id: string) => Promise<SynqResult<null>>;
+  };
+  /** Each browser plugin's actions, by its id (`usePlugin` types them). */
+  readonly plugins: Readonly<Record<string, unknown>>;
+}
+/** Everything the signed-in person can do. */
+export declare function useAuth(): UseAuth;
+//#endregion
+//#region src/components/SignedIn.d.ts
+/** Shows its children only while someone is signed in. It renders no element of its own. */
+export declare function SignedIn({ children }: {
+  readonly children?: ReactNode;
+}): ReactNode;
+//#endregion
+//#region src/components/SignedOut.d.ts
+/** Shows its children only once the app has said nobody is signed in. It renders no element of its own. */
+export declare function SignedOut({ children }: {
+  readonly children?: ReactNode;
+}): ReactNode;
+//#endregion
+//#region src/components/styling.d.ts
+/** What every component takes for its look: Synq's classes, or `unstyled`. */
+interface SynqStyleProps {
+  /** The same elements, roles and labels, with none of Synq's classes: the app styles them. */
+  readonly unstyled?: boolean;
+  /** Added to the component's outer element. */
+  readonly className?: string;
+}
+//#endregion
+//#region src/components/SignInButton.d.ts
+/** What `SignInButton` takes: the sign-in's options, its look and its words. */
+interface SignInButtonProps extends SignInOptions, SynqStyleProps {
+  /** Its label: the provider's `messages.signIn` by default. */
+  readonly children?: ReactNode;
+}
+/** 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/UserButton.d.ts
+/** What `UserButton` takes: where its account link goes, and its look. */
+interface UserButtonProps extends SynqStyleProps {
+  /** The app's page with `<AccountManager>`, linked as "Manage account". */
+  readonly accountHref?: string;
+}
+/**
+ * The signed-in person's picture and name, showing a panel to manage their
+ * account or sign out: a disclosure (a button that shows and hides it), so
+ * its link and button are reached with Tab as anywhere else. Escape or a
+ * click elsewhere hides it. Nothing while nobody is signed in.
+ */
+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';
+/** 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. */
+  readonly sections?: readonly AccountSection[];
+}
+/** Manage the signed-in person's account. Nothing while nobody is signed in. */
+export declare function AccountManager({ unstyled, className, sections }: AccountManagerProps): ReactNode;
+//#endregion
+//#region src/components/WalletManager.d.ts
+/** What `WalletManager` takes: its look. */
+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 };