cauthy-auth 0.31.0 → 0.32.0

package/README.md

@@ -56,6 +56,7 @@ export const auth = createCauthy({ pages: { signIn: '/sign-in', resetPassword: '
 ```tsx
 import { AcceptInvite, ResetPassword, VerifyEmail } from 'cauthy-auth/react'
 <AcceptInvite links={{ signIn: '/sign-in' }} returnTo="/" />   // "You've been invited to Acme", a password, signed in
+<AcceptInvite onSaved={(e) => track(e.kind)} />                // 'invitation.accepted', with the address
 
 const { invitation, acceptInvitation } = useAuth()               // or with your own form
 ```
@@ -65,8 +66,19 @@ The forms follow what the workspace turned on in Cauthy's dashboard: each provid
 And the person's account, in your application: name, password, second step, sessions.
 
 ```tsx
-import { Account } from 'cauthy-auth/react'
+import { Account, AccountPasskeys } from 'cauthy-auth/react'
 <Account />                                  // or: const { account } = useAuth()
+<Account sections={['profile', 'password', 'sessions']} onSaved={(e) => toast(e.kind)} />
+<AccountPasskeys />                          // each part on its own card
+```
+
+`sections` lists the parts shown, in that order: `profile`, `email`, `password`, `linked`, `secondStep`, `phone`, `passkeys`, `agents`, `sessions` (default: all). Each is also its own component: `AccountProfile`, `AccountEmail`, `AccountPassword`, `AccountLinked`, `AccountSecondStep`, `AccountPhone`, `AccountPasskeys`, `AccountAgents`, `AccountSessions`. `onSaved` is called after every change saved, with `{ kind, ... }`: `profile.saved`, `email.change_requested`, `password.changed`, `identity.linked`, `identity.unlinked`, `mfa.enabled`, `mfa.disabled`, `recovery_codes.regenerated`, `phone.added`, `phone.removed`, `passkey.added`, `passkey.removed`, `agent.disconnected`, `sessions.ended`.
+
+The legal documents a signed-in person still owes (a new version of the terms), with the action that accepts them. It shows nothing when nothing is owed:
+
+```tsx
+import { PendingTerms } from 'cauthy-auth/react'
+<PendingTerms onSuccess={() => refresh()} />  // or: account.legal(), account.acceptLegal()
 ```
 
 And the person's organizations, run by their own members: the people of one, and the organization itself. Cauthy decides each change by the person's role in the system's catalog, with their own session:
@@ -74,6 +86,12 @@ And the person's organizations, run by their own members: the people of one, and
 ```tsx
 import { OrganizationMembers } from 'cauthy-auth/react'
 <OrganizationMembers organizationId={org.id} />   // shows only what the person's role allows
+<OrganizationMembers
+  organizationId={org.id}
+  roles={(role) => role !== 'billing'}             // the roles offered when adding or changing one
+  hide={['archive', 'delete']}                    // never offered: 'archive', 'delete', 'rename', 'leave'
+  onSaved={(e) => toast(e.kind)}                  // member.added, member.role_changed, member.removed, member.left,
+/>                                                // member.invited_again, organization.renamed, .archived, .deleted
 
 const { organizations } = useAuth()
 const [org] = await organizations.list()         // org.can: { readMembers, manageMembers, removeMembers, update, archive, delete }
@@ -155,7 +173,27 @@ The ready-made forms wear the look set for your application in Cauthy's dashboar
 import 'cauthy-auth/styles.css'
 ```
 
-Or draw them with your own `components` and `classNames`, and pass `unstyled`. The dashboard can start the look from your stylesheet (shadcn/ui and Tailwind, Stackmyth, or variables of your own); `npx cauthy-auth theme --css src/app/globals.css` reads it the same way from a terminal.
+Or draw them with your own `components` and `classNames`, and pass `unstyled`. Every part the forms draw can be yours; a part not given is drawn as before. With every part given and `unstyled`, the forms add only structural wrappers (`div`, `form`, `section`, lists):
+
+```tsx
+<SignIn unstyled components={{ Button, Input, Checkbox, Select, Field, Text, Badge, Link, Divider, Alert, Confirm }} />
+```
+
+| Part | Is given |
+| --- | --- |
+| `Button` | `type`, `disabled`, `className`, `onClick`, `children` |
+| `Input` | `id`, `name`, `type`, `value`, `autoComplete`, `required`, `className`, `aria-invalid`, `aria-describedby`, `onChange(e)` |
+| `Checkbox` | `id`, `name`, `checked`, `required`, `disabled`, `className`, `onChange(checked)`, `children` (its label) |
+| `Select` | `id`, `name`, `value`, `options: { value, label }[]`, `disabled`, `className`, `aria-label`, `onChange(value)` |
+| `Field` | `id`, `label`, `aside`, `help`, `error`, `required`, `className`, `children` (the control). Give the help the id `${id}-hint` and the error `${id}-error` |
+| `Text` | `as` (`p`, `span`, `h2`), `tone` (`muted`, `danger`, `success`), `size` (`sm`, `md`, `lg`), `children` |
+| `Badge` | `tone` (`neutral`, `success`, `warning`, `danger`), `children` |
+| `Link` | `href`, `onClick`, `newTab`, `children` |
+| `Divider` | `label` |
+| `Alert` | `tone` (`danger`, `info`, `success`), `children`. Announce it: `role="alert"` or `role="status"` |
+| `Confirm` | A function, `({ title, body, confirmLabel, cancelLabel, danger }) => Promise<boolean>`: your own dialog before removing a member, leaving, archiving or deleting. Without it, the question shows inline |
+
+`texts` changes any sentence. Its keys are stable: `email`, `password`, `name`, `code`, `signIn`, `signUp`, `continueWith`, `orWithEmail`, `forgotPassword`, `noAccount`, `createAccount`, `company`, `iAccept`, `and`, `termsOfService`, `privacyPolicy`, `haveAccount`, `sendLink`, `linkSent`, `codeHelp`, `codeHelpPhone`, `codeHelpEmail`, `sendEmailAgain`, `sendCodeSms`, `sendCodeWhatsapp`, `codeSent`, `pushSend`, `pushPick`, `pushWaiting`, `phone`, `phoneHelp`, `phoneOn`, `phoneOff`, `addPhone`, `removePhone`, `bySms`, `byWhatsapp`, `channel`, `verify`, `checkEmail`, `backToSignIn`, `emailMeALink`, `usePasskey`, `codeFromMail`, `signInLinkSent`, `newPassword`, `savePassword`, `passwordChanged`, `confirming`, `emailConfirmed`, `invitedTo`, `invitedToOrganization`, `invitedAs`, `choosePassword`, `acceptInvite`, `openingInvitation`, `invitationInvalid`, `profile`, `save`, `saved`, `currentPassword`, `changePassword`, `passwordChangedHere`, `secondStep`, `secondStepOn`, `secondStepOff`, `turnOn`, `turnOff`, `addToApp`, `openInApp`, `recoveryCodes`, `newRecoveryCodes`, `keepCodes`, `passkeys`, `managePasskeys`, `passkeysHelp`, `noPasskeys`, `passkeyName`, `addPasskey` (unused), `addPasskeyDevice`, `addSecurityKey`, `passkeyKinds`, `removePasskey`, `passkeyAdded`, `passkeyUnnamed`, `sessions`, `signOutEverywhere`, `agents`, `agentsHelp`, `disconnect`, `anAgent`, `unknownDevice`, `emailAddress`, `newEmail`, `changeEmail`, `emailSent`, `linkedAccounts`, `noLinkedAccounts`, `linkWith`, `unlink`, `linked`, `ssoOnly`, `members`, `membersHidden`, `organizationMissing`, `memberYou`, `memberInvited`, `memberManager`, `memberRole`, `memberAdd`, `memberAdded`, `memberRemove`, `memberRemoveConfirm`, `memberLeave`, `memberLeaveConfirm`, `memberInviteAgain`, `memberInvitationSent`, `organization`, `organizationRename`, `organizationRenamed`, `organizationArchive`, `organizationArchiveConfirm`, `organizationArchived`, `organizationDelete`, `organizationDeleteConfirm`, `organizationDeleted`, `yes`, `cancel`, `termsChanged`, `termsChangedHelp`, `acceptTerms`, and `errors` by error code. Built in: English and Spanish (`locale`). The dashboard can start the look from your stylesheet (shadcn/ui and Tailwind, Stackmyth, or variables of your own); `npx cauthy-auth theme --css src/app/globals.css` reads it the same way from a terminal.
 
 Connect your application to Cauthy in one step, from Cauthy's dashboard ("Connect a System") or from a terminal. In the application's folder, `init` reads its framework (Next.js, TanStack Start, React Router or Remix, SvelteKit, Vite + React, Express, Hono, Fastify), makes the client, writes every variable to its env file, `CAUTHY_SECRET` included, and lays down the route and a sign-in page, never over a file that is there:
 

package/dist/react.d.mts

@@ -1180,6 +1180,8 @@ interface AuthTexts {
     removePhone: string;
     bySms: string;
     byWhatsapp: string;
+    /** The label of the channel phone codes go by, where the application draws it as a select. */
+    channel: string;
     verify: string;
     checkEmail: string;
     backToSignIn: string;
@@ -1271,6 +1273,9 @@ interface AuthTexts {
     organizationDeleted: string;
     yes: string;
     cancel: string;
+    termsChanged: string;
+    termsChangedHelp: string;
+    acceptTerms: string;
     /** By error code; one missing shows what the server said. */
     errors: Record<string, string>;
 }
@@ -1313,34 +1318,138 @@ interface AuthFormProps {
      */
     workspaceLook?: boolean;
     /**
-     * The application's own button and input, to draw the form with. Each is
-     * given what a `<button>` or an `<input>` would be.
+     * The application's own parts, to draw the form with: its button, input,
+     * checkbox, select, field, text, badge, link, divider, alert and
+     * confirmation. A part not given is drawn as before; with every part given
+     * and `unstyled`, the form adds no element that carries a look of its own.
      */
-    components?: {
-        Button?: ComponentType<{
-            type: 'submit' | 'button';
-            disabled?: boolean;
-            className?: string;
-            onClick?: () => void;
-            children: ReactNode;
-        }>;
-        Input?: ComponentType<{
-            id: string;
-            name: string;
-            type: string;
+    components?: AuthComponents;
+}
+/** What the application's button is given: what a `<button>` would be. */
+interface AuthButtonProps {
+    type: 'submit' | 'button';
+    disabled?: boolean;
+    className?: string;
+    onClick?: () => void;
+    children: ReactNode;
+}
+/** What the application's input is given: what an `<input>` would be. */
+interface AuthInputProps {
+    id: string;
+    name: string;
+    type: string;
+    value: string;
+    autoComplete?: string;
+    required?: boolean;
+    className?: string;
+    'aria-invalid'?: boolean;
+    'aria-describedby'?: string;
+    onChange: (e: {
+        target: {
             value: string;
-            autoComplete?: string;
-            required?: boolean;
-            className?: string;
-            'aria-invalid'?: boolean;
-            'aria-describedby'?: string;
-            onChange: (e: {
-                target: {
-                    value: string;
-                };
-            }) => void;
-        }>;
-    };
+        };
+    }) => void;
+}
+/** A box to tick: the legal documents and each consent of a sign-up. `children` is its label. */
+interface AuthCheckboxProps {
+    id: string;
+    name: string;
+    checked: boolean;
+    required?: boolean;
+    disabled?: boolean;
+    className?: string;
+    onChange: (checked: boolean) => void;
+    children: ReactNode;
+}
+/** One choice of a few: a member's role, the channel of phone codes. Without a visible label it carries `aria-label`. */
+interface AuthSelectProps {
+    id: string;
+    name: string;
+    value: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    disabled?: boolean;
+    className?: string;
+    'aria-label'?: string;
+    onChange: (value: string) => void;
+}
+/**
+ * A label, its control (`children`) and what is said under it. The control's
+ * `aria-describedby` names `${id}-hint` and `${id}-error`: give the help and
+ * the error those ids for a screen reader to read them with it.
+ */
+interface AuthFieldProps {
+    id: string;
+    label: ReactNode;
+    children: ReactNode;
+    /** Beside the label: "Forgot your password?". */
+    aside?: ReactNode;
+    /** What the field takes (a new password's rule). Not given while there is an error. */
+    help?: ReactNode;
+    error?: ReactNode;
+    required?: boolean;
+    className?: string;
+}
+/** A sentence of the form: help, a state, the footer (`size: 'sm'`), a section's heading (`as: 'h2'`). */
+interface AuthTextProps {
+    as?: 'p' | 'span' | 'h2';
+    tone?: 'muted' | 'danger' | 'success';
+    size?: 'sm' | 'md' | 'lg';
+    children: ReactNode;
+}
+/** A short mark beside a name: "you", "invited", a role, a passkey's kind. */
+interface AuthBadgeProps {
+    tone?: 'neutral' | 'success' | 'warning' | 'danger';
+    children: ReactNode;
+}
+/** A link: to another screen, or a legal document (`newTab`). */
+interface AuthLinkProps {
+    href?: string;
+    onClick?: () => void;
+    newTab?: boolean;
+    children: ReactNode;
+}
+/** The line between the providers and the address: "or with your email". */
+interface AuthDividerProps {
+    label?: ReactNode;
+}
+/**
+ * What went wrong (`danger`), what was done (`success`) or what to know
+ * (`info`). The built-in one is announced: `role="alert"` for danger,
+ * `role="status"` otherwise; the application's should be too.
+ */
+interface AuthAlertProps {
+    tone: 'danger' | 'info' | 'success';
+    children: ReactNode;
+}
+/** What a confirmation asks: removing a member, leaving, archiving or deleting the organization. */
+interface AuthConfirmOptions {
+    title: string;
+    body?: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    danger?: boolean;
+}
+/** The parts a form may be drawn with. See `AuthFormProps.components`. */
+interface AuthComponents {
+    Button?: ComponentType<AuthButtonProps>;
+    Input?: ComponentType<AuthInputProps>;
+    Checkbox?: ComponentType<AuthCheckboxProps>;
+    Select?: ComponentType<AuthSelectProps>;
+    Field?: ComponentType<AuthFieldProps>;
+    Text?: ComponentType<AuthTextProps>;
+    Badge?: ComponentType<AuthBadgeProps>;
+    Link?: ComponentType<AuthLinkProps>;
+    Divider?: ComponentType<AuthDividerProps>;
+    Alert?: ComponentType<AuthAlertProps>;
+    /**
+     * Asks before something that cannot be undone, and answers whether to go
+     * on: the application's own dialog. Not given: the question shows inline,
+     * with a yes and a cancel button. Never the browser's own dialog.
+     */
+    Confirm?: (options: AuthConfirmOptions) => Promise<boolean>;
 }
 declare function SignIn(props: AuthFormProps): react.JSX.Element;
 interface GoogleOneTapProps {
@@ -1371,12 +1480,84 @@ declare function VerifyEmail(props: AuthFormProps): react.JSX.Element;
  * `returnTo`. The invitation is good until it is accepted: reading it, or a
  * password refused, does not spend it.
  */
-declare function AcceptInvite(props: AuthFormProps): react.JSX.Element;
+/** What `<AcceptInvite />` tells the application once the invitation is accepted. */
+type AcceptInviteEvent = {
+    kind: 'invitation.accepted';
+    email: string;
+    organization?: string;
+};
+interface AcceptInviteProps extends AuthFormProps {
+    /** Called once the invitation is accepted, before the second step when the account owes one. */
+    onSaved?: (event: AcceptInviteEvent) => void;
+}
+declare function AcceptInvite(props: AcceptInviteProps): react.JSX.Element;
+interface PendingTermsProps extends Omit<AuthFormProps, 'links' | 'returnTo' | 'createAccounts'> {
+    /** Called once the person accepted. Nothing else happens: the application decides what follows. */
+    onSuccess?: () => void;
+}
+/**
+ * The legal documents the signed-in person still owes (a new version of the
+ * terms, say), linked, with the action that accepts them. It shows nothing
+ * while it reads them, when nothing is owed, and once they are accepted.
+ * Nothing stops the person meanwhile: the application decides what waits.
+ */
+declare function PendingTerms(props: PendingTermsProps): react.JSX.Element | null;
+/** The parts of `<Account />`, by name: what `sections` lists. */
+type AccountSection = 'profile' | 'email' | 'password' | 'linked' | 'secondStep' | 'phone' | 'passkeys' | 'agents' | 'sessions';
+/**
+ * What `<Account />` tells the application after each change it saved, for
+ * the application's own toast or its own data to follow.
+ */
+type AccountEvent = {
+    kind: 'profile.saved';
+    name: string;
+} | {
+    kind: 'email.change_requested';
+    email: string;
+} | {
+    kind: 'password.changed';
+} | {
+    kind: 'identity.linked';
+    provider: string;
+} | {
+    kind: 'identity.unlinked';
+    provider: string;
+} | {
+    kind: 'mfa.enabled';
+} | {
+    kind: 'mfa.disabled';
+} | {
+    kind: 'recovery_codes.regenerated';
+} | {
+    kind: 'phone.added';
+    channel: 'sms' | 'whatsapp';
+} | {
+    kind: 'phone.removed';
+} | {
+    kind: 'passkey.added';
+    id: string;
+} | {
+    kind: 'passkey.removed';
+    id: string;
+} | {
+    kind: 'agent.disconnected';
+    id: string;
+} | {
+    kind: 'sessions.ended';
+};
 interface AccountProps extends Omit<AuthFormProps, 'links' | 'returnTo' | 'onSuccess'> {
     /** Called after "sign out everywhere". Default: go to `/`. */
     onSignedOut?: () => void;
     /** The moment of a session, as the application writes dates. Default: the browser's own way, in the reader's time zone. */
     formatDate?: (iso: string) => string;
+    /**
+     * The parts shown, in this order. Default: all of them, as listed in
+     * `AccountSection`. A part with nothing to show (the password of an account
+     * without one, agents when none is connected) stays out either way.
+     */
+    sections?: AccountSection[];
+    /** Called after every change saved, with what changed. */
+    onSaved?: (event: AccountEvent) => void;
 }
 /**
  * The signed-in person's account, in the application: their name, their
@@ -1384,11 +1565,82 @@ interface AccountProps extends Omit<AuthFormProps, 'links' | 'returnTo' | 'onSuc
  * its own. Like the other forms, it carries no styles.
  */
 declare function Account(props: AccountProps): react.JSX.Element;
+/** What each part of the account screen takes, shown on its own: `<Account />`'s props but `sections`. */
+type AccountPartProps = Omit<AccountProps, 'sections'>;
+/** The person's name. */
+declare function AccountProfile(props: AccountPartProps): react.JSX.Element;
+/** Changing the address: a link goes to the new one. */
+declare function AccountEmail(props: AccountPartProps): react.JSX.Element;
+/** Changing the password, for an account that has one. */
+declare function AccountPassword(props: AccountPartProps): react.JSX.Element;
+/** The providers the account signs in with. */
+declare function AccountLinked(props: AccountPartProps): react.JSX.Element;
+/** The second step with an authenticator app, and the recovery codes. */
+declare function AccountSecondStep(props: AccountPartProps): react.JSX.Element;
+/** The phone codes go to, where the workspace sends them. */
+declare function AccountPhone(props: AccountPartProps): react.JSX.Element;
+/** The account's passkeys. */
+declare function AccountPasskeys(props: AccountPartProps): react.JSX.Element;
+/** The AI agents the person connected, when there is one. */
+declare function AccountAgents(props: AccountPartProps): react.JSX.Element;
+/** Where the person is signed in, and "sign out everywhere". */
+declare function AccountSessions(props: AccountPartProps): react.JSX.Element;
+/** An action `<OrganizationMembers hide={...} />` never offers. */
+type OrganizationMembersAction = 'archive' | 'delete' | 'rename' | 'leave';
+/**
+ * What `<OrganizationMembers />` tells the application after each change it
+ * saved, for the application's own toast or its own data to follow.
+ */
+type OrganizationMembersEvent = {
+    kind: 'member.added';
+    organizationId: string;
+    userId: string;
+    email: string;
+    role: string;
+} | {
+    kind: 'member.role_changed';
+    organizationId: string;
+    userId: string;
+    role: string;
+    previousRole: string;
+} | {
+    kind: 'member.removed';
+    organizationId: string;
+    userId: string;
+} | {
+    kind: 'member.left';
+    organizationId: string;
+    userId: string;
+} | {
+    kind: 'member.invited_again';
+    organizationId: string;
+    userId: string;
+} | {
+    kind: 'organization.renamed';
+    organizationId: string;
+    name: string;
+} | {
+    kind: 'organization.archived';
+    organizationId: string;
+} | {
+    kind: 'organization.deleted';
+    organizationId: string;
+};
 interface OrganizationMembersProps extends Omit<AuthFormProps, 'links' | 'returnTo' | 'onSuccess' | 'createAccounts'> {
     /** The organization, by the id Cauthy gave it. */
     organizationId: string;
     /** The moment of a membership, as the application writes dates. Default: the browser's own way. */
     formatDate?: (iso: string) => string;
+    /**
+     * The roles offered when adding a member or changing one's role: those for
+     * which it answers true. A member already holding another role keeps it,
+     * and it shows. Default: every role the person may give.
+     */
+    roles?: (role: string, choice: OrganizationRoleChoice) => boolean;
+    /** Actions never offered, whatever the person's role allows. */
+    hide?: OrganizationMembersAction[];
+    /** Called after every change saved, with what changed. */
+    onSaved?: (event: OrganizationMembersEvent) => void;
 }
 /**
  * The people of one of the signed-in person's organizations, administered
@@ -1446,4 +1698,4 @@ declare function useSession(): SessionContext;
  */
 declare function useAuth(): AuthClient & Pick<SessionContext, 'session' | 'status' | 'refresh'>;
 
-export { AcceptInvite, Account, type AccountClient, type Account$1 as AccountDetails, type AccountProps, type AccountSession, type AuthClient, type AuthError, type AuthFormProps, type AuthMethods, type AuthResult, type AuthTexts, CauthyProvider, type CauthyProviderProps, type ConnectedAgent, ForgotPassword, GoogleOneTap, type GoogleOneTapProps, type Invitation, type JsonValue, type LinkedIdentity, OrganizationMembers, type OrganizationMembersProps, type OrganizationPerson, type OrganizationRoleChoice, type OrganizationSeat, type OrganizationsClient, type Passkey, type PasskeyKind, type PermissionOf, type Policy, type PublicSession, ResetPassword, type RoleOf, type SSOConnection, type SecondStep, type SessionContext, type SessionOrganization, type SessionUser, SignIn, SignUp, VerifyEmail, can, canAutofillPasskeys, canUsePasskeys, createAuthClient, definePolicy, useAuth, useSession };
+export { AcceptInvite, type AcceptInviteEvent, type AcceptInviteProps, Account, AccountAgents, type AccountClient, type Account$1 as AccountDetails, AccountEmail, type AccountEvent, AccountLinked, type AccountPartProps, AccountPasskeys, AccountPassword, AccountPhone, AccountProfile, type AccountProps, AccountSecondStep, type AccountSection, type AccountSession, AccountSessions, type AuthAlertProps, type AuthBadgeProps, type AuthButtonProps, type AuthCheckboxProps, type AuthClient, type AuthComponents, type AuthConfirmOptions, type AuthDividerProps, type AuthError, type AuthFieldProps, type AuthFormProps, type AuthInputProps, type AuthLinkProps, type AuthMethods, type AuthResult, type AuthSelectProps, type AuthTextProps, type AuthTexts, CauthyProvider, type CauthyProviderProps, type ConnectedAgent, ForgotPassword, GoogleOneTap, type GoogleOneTapProps, type Invitation, type JsonValue, type LinkedIdentity, OrganizationMembers, type OrganizationMembersAction, type OrganizationMembersEvent, type OrganizationMembersProps, type OrganizationPerson, type OrganizationRoleChoice, type OrganizationSeat, type OrganizationsClient, type Passkey, type PasskeyKind, type PendingLegal, PendingTerms, type PendingTermsProps, type PermissionOf, type Policy, type PublicSession, ResetPassword, type RoleOf, type SSOConnection, type SecondStep, type SessionContext, type SessionOrganization, type SessionUser, SignIn, SignUp, VerifyEmail, can, canAutofillPasskeys, canUsePasskeys, createAuthClient, definePolicy, useAuth, useSession };