@elvix.is/sdk 0.5.7 → 0.5.9

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties } from 'react';
-import { ElvixActionResult } from './index.js';
-export { ElvixUser, ElvixVerifyResult } from './index.js';
+import { z } from 'zod';
+export { ElvixActionResult, ElvixUser, ElvixVerifyResult } from './index.js';
 
 /** Size overrides every <Elvix*> component accepts so hosts can fit it to any slot. */
 type ElvixSizeProps = {
@@ -184,14 +184,49 @@ type ElvixSignInResult$1 = ElvixSignInResultOk | ElvixSignInResultErr;
 /** Theme override. Omit to inherit the Console-configured pair. */
 type ElvixTheme = "light" | "dark" | "system";
 
+/**
+ * Per-app user envelope returned by
+ * `GET /api/account/apps/<clientId>/sdk-context`. The provider fetches it on
+ * mount alongside the public bootstrap whenever a session is present (cookie
+ * same-origin, bearer cross-origin). Mirrors the monorepo `ElvixAppContext`
+ * shape exactly so the ported `<Elvix*>` identity / account components read
+ * `useElvixAppContext()` and skip the `appId` / `appName` / `current` /
+ * `membership` props a host would otherwise thread down. `null` while loading,
+ * with no `clientId`, or when there's no user session (the SDK falls back to
+ * its empty / "sign in to see this" state).
+ */
+type ElvixAppContext = {
+    user: {
+        id: string;
+        name: string | null;
+        email: string | null;
+        avatarUrl: string | null;
+    };
+    membership: {
+        username: string | null;
+        status: string;
+        inactiveAt: string | null;
+        inactivatedBy: string | null;
+        deletedAt: string | null;
+        deletedBy: string | null;
+        avatarSizes: number[];
+        avatarUpdatedAt: string;
+        bannerSizes: number[];
+        bannerUpdatedAt: string;
+    } | null;
+};
 type ElvixContextValue = {
     clientId: string | undefined;
     baseUrl: string;
     app: ElvixBootstrapEnvelope | null;
     appError: string | null;
+    appContext: ElvixAppContext | null;
     resolvedTheme: "light" | "dark";
 };
 declare function useElvixApp(): ElvixBootstrapEnvelope | null;
+/** Per-app signed-in user envelope (session-bound). `null` while loading,
+ *  with no clientId, or when there's no user session. */
+declare function useElvixAppContext(): ElvixAppContext | null;
 declare function useElvixContext(): ElvixContextValue;
 declare function ElvixProvider({ clientId, theme, brand, baseUrl, children, className, }: {
     clientId?: string;
@@ -397,6 +432,27 @@ type AuthFormProps = {
         redirect?: string;
         token?: string;
     }) => void;
+    /**
+     * Where to send the user after EVERY terminal success path. One prop, one
+     * destination — no per-method customisation. Applies uniformly to:
+     *
+     *   - OTP verify success (with or without an onboarding step).
+     *   - Google sign-in (both the GIS credential and the redirect-OAuth
+     *     return path that consumes `#elvix_token=...` on mount).
+     *   - Passkey sign-in.
+     *   - The onboarding "Add a passkey" success.
+     *   - The onboarding "Skip for now" button on the passkey step.
+     *   - The onboarding username step success.
+     *
+     * Resolution order at the moment of navigation:
+     *   `redirectAfterSignIn ?? <backend-provided redirect> ?? "/"`
+     *
+     * If a host wants different destinations per method, they should switch
+     * on the result inside `onResult`/`onAuthenticated` and call
+     * `router.push(...)` themselves; this prop is the single declarative
+     * fallback that ALL success paths honour.
+     */
+    redirectAfterSignIn?: string;
     /**
      * Fires on every terminal outcome: success AND every error path
      * (invalid OTP, expired challenge, rate-limited, network blip,
@@ -472,6 +528,18 @@ declare function ElvixSecuredBadge({ variant, size, theme, accentColor, href, cl
 declare function getElvixToken(): string | null;
 /** Store (or clear with null) the session token. Persists to localStorage. */
 declare function setElvixToken(token: string | null): void;
+/**
+ * On the host page, pick up a session token handed back by elvix's Google
+ * redirect-callback in the URL fragment, store it, and strip it from the URL
+ * so a refresh/back-nav doesn't replay it (and it never leaks into history,
+ * referrers, or analytics). Returns the token it consumed, or null.
+ *
+ * Idempotent and SSR-safe: a no-op (returns null) when there's no `window` or
+ * no `#elvix_token=` present. `<ElvixProvider>` calls this automatically on
+ * mount; hosts that don't mount the provider at the redirect target can call
+ * it directly (it's exported from `@elvix.is/sdk/react`).
+ */
+declare function consumeElvixReturnToken(): string | null;
 
 type UseUserListResult = {
     slugs: string[];
@@ -491,125 +559,516 @@ declare const useUserRoles: (opts: Opts) => UseUserListResult;
 declare const useUserScopes: (opts: Opts) => UseUserListResult;
 declare const useUserMemberships: (opts: Opts) => UseUserListResult;
 
-declare function ElvixLifecycleWatcher({ baseUrl, pollMs, onSignedOut, }: {
+type ElvixLifecycleWatcherProps = {
     /** elvix origin. Defaults to "" (same-origin). */
     baseUrl?: string;
-    /** Poll interval in ms. Default 7000. */
+    /** Poll interval in ms when SSE isn't available. Default 7000. */
     pollMs?: number;
+    /**
+     * Application id to subscribe to (SSE mode). When set together with
+     * `userId` AND we're same-origin with `baseUrl`, the watcher opens an
+     * EventSource on `/api/presence/stream` and skips polling entirely.
+     * Omit to force the polling path (the cross-origin SDK case).
+     */
+    applicationId?: string;
+    /** User id to watch — SSE filters by this. Required with `applicationId`. */
+    userId?: string;
     /** Called once with the reason when the session ends. Defaults to a reload. */
     onSignedOut?: (reason: string) => void;
-}): null;
+};
+declare function ElvixLifecycleWatcher({ baseUrl, pollMs, applicationId, userId, onSignedOut, }: ElvixLifecycleWatcherProps): null;
 
-/**
- * `<ElvixUsername>` — claim or change the end-user's username for the
- * current Application. PATCH /api/account/apps/<appId>/username.
- * Render a single in-frame card with two panes: edit + done.
- */
-declare function ElvixUsername({ onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixActionResult<{
-        username: string;
-    }>) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+type ElvixUsernameResult = {
+    ok: true;
+    username: string;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+declare function ElvixUsername(props: ElvixUsernameProps): react_jsx_runtime.JSX.Element;
+type ElvixUsernameProps = {
+    appId?: string;
+    appName?: string;
+    current?: string | null;
+    methodUsername?: boolean;
+    supportUrl?: string | null;
+    supportEmail?: string | null;
+    onSuccess?: (value: string) => void;
+    onFail?: (error: string) => void;
+    onResult?: (result: ElvixUsernameResult) => void;
+};
 
-/**
- * `<ElvixAvatar>` — upload / replace the end-user's avatar for this
- * Application. Reads file → base64 → PATCH /api/account/apps/<appId>/avatar.
- */
-declare function ElvixAvatar({ onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixActionResult<{
-        avatarUrl: string;
-    }>) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+declare const Shape: {
+    readonly CIRCLE: "circle";
+    readonly SQUARE: "square";
+};
+type Shape = (typeof Shape)[keyof typeof Shape];
+type UserAvatarProps = {
+    /** App slug — Application.urlSlug. */
+    appSlug: string;
+    userId: string;
+    membership: {
+        avatarUpdatedAt: Date | number;
+        avatarSizes: number[];
+    };
+    user: {
+        name?: string | null;
+        email?: string | null;
+        avatarUrl?: string | null;
+    };
+    /** Pixel display size (1× CSS px). srcset handles retina automatically. */
+    size?: number;
+    className?: string;
+    /** Round vs square. Default rounded-full. */
+    shape?: Shape;
+};
 
-/**
- * `<ElvixBanner>` — upload / replace the end-user's profile banner
- * (16:9 cover image) for this Application.
- */
-declare function ElvixBanner({ onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixActionResult<{
-        bannerUrl: string;
-    }>) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+type ElvixAvatarResult = {
+    ok: true;
+    sizes: number[];
+    updatedAt: string;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+type ElvixAvatarProps = Omit<UserAvatarProps, "size"> & {
+    applicationId: string;
+    /** Diameter (px). Default 128. The widget stays at this size in
+     *  every state — no expand-on-edit. */
+    size?: number;
+    /** Fired after a successful upload / remove. */
+    onChange?: (next: {
+        sizes: number[];
+        updatedAt: Date | number;
+    }) => void;
+    /** Fires on every terminal upload / remove outcome. Safe payload:
+     *  rendered avatar sizes + updatedAt only (no image bytes). */
+    onResult?: (result: ElvixAvatarResult) => void;
+};
+declare function ElvixAvatar(props: Partial<ElvixAvatarProps>): react_jsx_runtime.JSX.Element;
 
-/**
- * `<ElvixIdentityForm>` — edit the end-user's display name + bio for
- * the current Application. Lightweight per-app profile fields.
- */
-declare function ElvixIdentityForm({ initialName, initialBio, onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    initialName?: string;
-    initialBio?: string;
-    onResult?: (r: ElvixActionResult<{
-        name: string;
-        bio: string;
-    }>) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+type UserBannerProps = {
+    appSlug: string;
+    userId: string;
+    membership: {
+        bannerUpdatedAt: Date | number;
+        bannerSizes: number[];
+    };
+    /** Container max-width in CSS px. Drives `sizes` for srcset. */
+    containerPx?: number;
+    className?: string;
+    /** Class for the empty placeholder background (gradient by default). */
+    emptyClassName?: string;
+};
 
-/**
- * `<ElvixRegion>` — set the end-user's region (ISO 3166-1 alpha-2
- * country code + timezone). Used by elvix for data-residency hints
- * and locale defaults.
- */
-declare function ElvixRegion({ initialCountry, initialTimezone, onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    initialCountry?: string;
-    initialTimezone?: string;
-    onResult?: (r: ElvixActionResult<{
-        country: string;
-        timezone: string;
-    }>) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+type ElvixBannerResult = {
+    ok: true;
+    sizes: number[];
+    updatedAt: string;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+type ElvixBannerProps = UserBannerProps & {
+    applicationId: string;
+    /** Corner radius for the frame. Default 14 (matches the SDK card chrome). */
+    cornerRadius?: number;
+    /** Fired after a successful upload / remove. */
+    onChange?: (next: {
+        sizes: number[];
+        updatedAt: Date | number;
+    }) => void;
+    /** Fires on every terminal upload / remove outcome. Safe payload:
+     *  rendered banner sizes + updatedAt only (no image bytes). */
+    onResult?: (result: ElvixBannerResult) => void;
+};
+declare function ElvixBanner(props: Partial<ElvixBannerProps>): react_jsx_runtime.JSX.Element;
 
-/**
- * `<ElvixLanguages>` — set the end-user's preferred languages (BCP-47
- * tag list, ordered by preference). The first entry drives UI locale.
- */
-declare function ElvixLanguages({ initial, onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    initial?: string[];
-    onResult?: (r: ElvixActionResult<{
-        languages: string[];
-    }>) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+declare const identitySchema: z.ZodObject<{
+    givenName: z.ZodString;
+    familyName: z.ZodString;
+    birthdate: z.ZodString;
+    gender: z.ZodEnum<{
+        male: "male";
+        female: "female";
+        non_binary: "non_binary";
+        prefer_not_to_say: "prefer_not_to_say";
+    }>;
+    pronouns: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+        other: "other";
+        prefer_not_to_say: "prefer_not_to_say";
+        she_her: "she_her";
+        he_him: "he_him";
+        they_them: "they_them";
+    }>>>;
+}, z.core.$strip>;
+type IdentityInput = z.infer<typeof identitySchema>;
 
-declare function ElvixSessions({ onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixActionResult<{
-        revoked: number;
-    }>) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+type ElvixIdentityFormResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+declare function ElvixIdentityForm({ initial, onResult, }: {
+    /**
+     * Pre-loaded identity fields. Optional — when omitted, the SDK
+     * fetches `/api/account/profile/identity` on mount so the
+     * customer doesn't have to thread server-side state in.
+     */
+    initial?: Partial<IdentityInput>;
+    /** Fires on every terminal save outcome. Safe payload: no PII —
+     *  identity edits are saved, not echoed back to the host. */
+    onResult?: (result: ElvixIdentityFormResult) => void;
+}): react_jsx_runtime.JSX.Element;
 
-/**
- * `<ElvixExport>` — GDPR Art. 15 data-export request. Triggers an
- * async server-side zip + emails a single-use download link to the
- * end-user's bound email address.
- */
-declare function ElvixExport({ onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixActionResult<{
-        requestId: string;
-    }>) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+type RegionRecord = {
+    id: string;
+    country: string;
+    uiLocale: string | null;
+    timeZone: string | null;
+    firstDayOfWeek: number;
+    timeFormat: string;
+    dateFormat: string;
+    numberFormat: string;
+    currency: string | null;
+    measurementSystem: string;
+    createdAt: string;
+    updatedAt: string;
+};
 
-declare function ElvixDeactivate({ onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixActionResult) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+type ElvixRegionResult = {
+    ok: true;
+    country: string;
+    locale: string;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+type ElvixRegionProps = {
+    height?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    width?: number | string;
+    onChange?: (region: RegionRecord | null) => void;
+    /** Fires on every terminal save outcome. Safe payload: country +
+     *  locale code only. `onChange` keeps firing too on every refresh. */
+    onResult?: (result: ElvixRegionResult) => void;
+};
+declare function ElvixRegion({ height, minHeight, maxHeight, width, onChange, onResult, }: ElvixRegionProps): react_jsx_runtime.JSX.Element;
 
-declare function ElvixLeave({ onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixActionResult) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+declare const languageSchema: z.ZodObject<{
+    code: z.ZodString;
+    level: z.ZodEnum<{
+        ELEMENTARY: "ELEMENTARY";
+        INTERMEDIATE: "INTERMEDIATE";
+        PROFICIENT: "PROFICIENT";
+        NATIVE: "NATIVE";
+    }>;
+}, z.core.$strip>;
+type LanguageInput = z.infer<typeof languageSchema>;
+type LanguageRecord = LanguageInput & {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+};
+
+type ElvixLanguagesResult = {
+    ok: true;
+    count: number;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+type ElvixLanguagesProps = {
+    height?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    width?: number | string;
+    onChange?: (languages: LanguageRecord[]) => void;
+    /** Fires on every terminal save outcome. Safe payload: count only. */
+    onResult?: (result: ElvixLanguagesResult) => void;
+};
+declare function ElvixLanguages({ height, minHeight, maxHeight, width, onChange, onResult, }: ElvixLanguagesProps): react_jsx_runtime.JSX.Element;
+
+declare const ElvixSessionsAction: {
+    readonly REVOKE_ONE: "revoke_one";
+    readonly SIGN_OUT_OTHERS: "sign_out_others";
+    readonly SIGN_OUT_ALL: "sign_out_all";
+};
+type ElvixSessionsAction = (typeof ElvixSessionsAction)[keyof typeof ElvixSessionsAction];
+type ElvixSessionsResult = {
+    ok: true;
+    action: ElvixSessionsAction;
+    ended?: number;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+declare function ElvixSessions({ appId, signInUrl, onChanged, onResult, }: {
+    /** When set, scopes the list to one customer app. When undefined,
+     *  lists `surface="account"` sessions. */
+    appId?: string;
+    /** Where to send the user after a "sign out everywhere too"
+     *  action. Defaults to elvix's account sign-in. */
+    signInUrl?: string;
+    onChanged?: () => void;
+    /** Fires on every terminal revoke outcome. Safe payload: action
+     *  kind + count of ended sessions. No session IDs leak to the host. */
+    onResult?: (result: ElvixSessionsResult) => void;
+}): react_jsx_runtime.JSX.Element;
+
+type ExportTarget = {
+    kind: "identity";
+} | {
+    kind: "app";
+    appId: string;
+    appName: string;
+};
+type ElvixExportResult = {
+    ok: true;
+    downloadId: string;
+    deliveredTo: string;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+declare function ElvixExport({ target, primaryEmail, onSuccess, onFail, onResult, }: {
+    /** Scope: identity-level export, or per-app export. Defaults to
+     *  identity — the most common surface. */
+    target?: ExportTarget;
+    /** Address the export zip is delivered to. Optional — when
+     *  omitted, the SDK reads it from the signed-in user's session
+     *  via `useElvixAppContext().user.email`. */
+    primaryEmail?: string;
+    onSuccess?: (downloadId: string) => void;
+    onFail?: (error: string) => void;
+    /** Fires on every terminal export outcome. Safe payload: the
+     *  single-use downloadId (only redeemable with the OTP-verified
+     *  session) + the email address the zip was sent to. */
+    onResult?: (result: ElvixExportResult) => void;
+}): react_jsx_runtime.JSX.Element;
+
+declare const State$1: {
+    readonly INACTIVE: "inactive";
+    readonly ACTIVE: "active";
+};
+type State$1 = (typeof State$1)[keyof typeof State$1];
+type ElvixDeactivateResult = {
+    ok: true;
+    state: State$1;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+declare function ElvixDeactivate(props: {
+    appId?: string;
+    appName?: string;
+    inactive?: boolean;
+    inactivatedBy?: string | null;
+    onSuccess?: (state: State$1) => void;
+    onFail?: (error: string) => void;
+    onResult?: (result: ElvixDeactivateResult) => void;
+}): react_jsx_runtime.JSX.Element;
+
+declare const State: {
+    readonly LEFT: "left";
+    readonly RESTORED: "restored";
+};
+type State = (typeof State)[keyof typeof State];
+type ElvixLeaveResult = {
+    ok: true;
+    state: State;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+declare function ElvixLeave(props: {
+    appId?: string;
+    appName?: string;
+    deletedAt?: string | null;
+    deletedBy?: string | null;
+    privacyPolicyUrl?: string | null;
+    termsOfServiceUrl?: string | null;
+    onSuccess?: (state: State) => void;
+    onFail?: (error: string) => void;
+    onResult?: (result: ElvixLeaveResult) => void;
+}): react_jsx_runtime.JSX.Element;
 
 /**
- * `<ElvixAddressBook>` — list / add / remove the end-user's addresses
- * on this Application. Read uses GET /api/account/apps/<appId>/addresses;
- * mutations POST + DELETE on the same path.
+ * Address schema for the elvix Profile SDK.
+ *
+ * Two flavours mirror the basic-info pattern:
+ *
+ *   `addressSchema`        — STRICT. SDK form enforces it client-side
+ *                            before submit.
+ *   `addressPatchSchema`   — LOOSE. Server-side accepts partial
+ *                            updates (single field PATCHs from admin
+ *                            tools, Google Places merges, etc.).
+ *
+ * Field shape mirrors DC EventAddress: country has both ISO code and
+ * human name; region has both code (ISO-3166-2) and name; coords are
+ * stored alongside Google Places provenance for shipping-zone /
+ * delivery-map use without re-geocoding.
  */
-declare function ElvixAddressBook({ onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixActionResult) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+declare const ADDRESS_KINDS: readonly ["billing", "shipping"];
+type AddressKind = (typeof ADDRESS_KINDS)[number];
+declare const addressSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        billing: "billing";
+        shipping: "shipping";
+    }>;
+    label: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    recipientName: z.ZodString;
+    companyName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    line1: z.ZodString;
+    line2: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    city: z.ZodString;
+    regionName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    regionCode: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    postalCode: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    country: z.ZodString;
+    countryName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    deliveryNotes: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    timezone: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    venueName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    placeId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    formattedAddress: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    latitude: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    longitude: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+type AddressInput = z.infer<typeof addressSchema>;
+/** Server response shape — adds id + audit fields. */
+type AddressRecord = AddressInput & {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+};
+
+type ElvixAddressBookResult = {
+    ok: true;
+    count: number;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+type ElvixAddressBookProps = {
+    kind: AddressKind;
+    /** Fixed frame height. Defaults to 520. Takes precedence over min/max. */
+    height?: number;
+    /** Bottom bound when `height` is unset. */
+    minHeight?: number;
+    /** Top bound when `height` is unset. */
+    maxHeight?: number;
+    /** Frame width. Defaults to "100%" so it fills whatever container
+     *  the host puts it in. Pass a number for a fixed pixel width. */
+    width?: number | string;
+    /**
+     * Signed-in user's display name. Powers the "Me" card on the
+     * recipient step so the user can pick their own name with one
+     * click. Falls back to email or "You" if the host doesn't provide.
+     */
+    userDisplayName?: string | null;
+    /** Optional callback fired after a successful save / delete. */
+    onChange?: (addresses: AddressRecord[]) => void;
+    /** Fires on every terminal save / delete outcome. Safe payload:
+     *  count only — never the address rows themselves. */
+    onResult?: (result: ElvixAddressBookResult) => void;
+};
+declare function ElvixAddressBook({ kind, height, minHeight, maxHeight, width, userDisplayName, onChange, onResult, }: ElvixAddressBookProps): react_jsx_runtime.JSX.Element;
 
 /**
- * `<ElvixLegalEntities>` — list / add / remove the end-user's legal
- * entities (company names + tax IDs) on this Application. Useful for
- * B2B apps that bill at the entity level.
+ * Strict schema layered atop the loose shape. The `superRefine` adds
+ * the per-type required-field gates the wizard enforces at commit
+ * time but server-PATCH endpoints don't want.
  */
-declare function ElvixLegalEntities({ onResult, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixActionResult) => void;
-} & ElvixSizeProps): react_jsx_runtime.JSX.Element;
+declare const legalEntitySchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        company: "company";
+        individual: "individual";
+        sole_prop: "sole_prop";
+    }>;
+    label: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    legalName: z.ZodString;
+    tradingName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    dateOfBirth: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    placeOfBirth: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    placeOfBirthPlaceId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    nationality: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    taxCountry: z.ZodString;
+    taxId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    vatId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    vatIdValidation: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        format: "format";
+        invalid: "invalid";
+        live: "live";
+    }>>;
+    vatIdValidatedAt: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    vatIdValidatedName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    registrationNumber: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    registrationBody: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    registeredSince: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    contactEmail: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    contactPhone: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressLine1: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressLine2: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressCity: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressRegionName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressRegionCode: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressPostalCode: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressCountry: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressCountryName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressFormatted: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressPlaceId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressTimezone: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    addressLatitude: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    addressLongitude: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+type LegalEntityInput = z.infer<typeof legalEntitySchema>;
+/** Server-emitted record. Adds audit fields, normalises dates to ISO. */
+type LegalEntityRecord = Omit<LegalEntityInput, "dateOfBirth" | "registeredSince"> & {
+    id: string;
+    dateOfBirth: string | null;
+    registeredSince: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+
+type ElvixLegalEntitiesResult = {
+    ok: true;
+    count: number;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+type ElvixLegalEntitiesProps = {
+    /** Fixed frame height. Defaults to 580. */
+    height?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    /** Frame width. Defaults to "100%". */
+    width?: number | string;
+    /** Optional callback fired after a successful save / delete. */
+    onChange?: (entities: LegalEntityRecord[]) => void;
+    /** Fires on every terminal save / delete outcome. Safe payload:
+     *  count only — never the entity rows themselves. */
+    onResult?: (result: ElvixLegalEntitiesResult) => void;
+};
+declare function ElvixLegalEntities({ height, minHeight, maxHeight, width, onChange, onResult, }: ElvixLegalEntitiesProps): react_jsx_runtime.JSX.Element;
 
-export { DEFAULT_COPY, ElvixActionResult, ElvixAddressBook, ElvixAvatar, ElvixBanner, type ElvixBootstrapEnvelope, type ElvixBrand, ElvixCard, type ElvixCopy, ElvixDeactivate, ElvixExport, ElvixIdentityForm, ElvixLanguages, ElvixLeave, ElvixLegalEntities, ElvixLifecycleWatcher, ElvixProvider, ElvixRegion, ElvixSecuredBadge, ElvixSessions, ElvixSignIn, ElvixSignInButton, ElvixSignInForm, type ElvixSignInMethod, type ElvixSignInResult$1 as ElvixSignInResult, type ElvixSignInResultErr, type ElvixSignInResultOk, type ElvixSizeProps, type ElvixTheme, ElvixUsername, type UseUserListResult, getElvixToken, setElvixToken, useElvixApp, useElvixContext, useUserMemberships, useUserRoles, useUserScopes };
+export { DEFAULT_COPY, ElvixAddressBook, type ElvixAppContext, ElvixAvatar, ElvixBanner, type ElvixBootstrapEnvelope, type ElvixBrand, ElvixCard, type ElvixCopy, ElvixDeactivate, ElvixExport, ElvixIdentityForm, ElvixLanguages, ElvixLeave, ElvixLegalEntities, ElvixLifecycleWatcher, ElvixProvider, ElvixRegion, ElvixSecuredBadge, ElvixSessions, ElvixSignIn, ElvixSignInButton, ElvixSignInForm, type ElvixSignInMethod, type ElvixSignInResult$1 as ElvixSignInResult, type ElvixSignInResultErr, type ElvixSignInResultOk, type ElvixSizeProps, type ElvixTheme, ElvixUsername, type UseUserListResult, consumeElvixReturnToken, getElvixToken, setElvixToken, useElvixApp, useElvixAppContext, useElvixContext, useUserMemberships, useUserRoles, useUserScopes };