@elvix.is/sdk 0.5.6 → 0.5.8

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 = {
@@ -136,6 +136,23 @@ type ElvixBootstrapEnvelope = {
     showHeader: boolean;
     transparentBg: boolean;
     signInVerb: "signin" | "login";
+    /**
+     * Per-app Google Identity Services config (One Tap / Auto-select / Popup
+     * / FedCM). Present on the wire; the SDK's `<ElvixSignInForm>` reads it
+     * into its resolved props. When any GIS flag is on AND `googleClientId`
+     * is present, the form swaps the static redirect anchor for Google's
+     * GIS-rendered personalized button.
+     */
+    googleConfig: unknown;
+    /**
+     * Public Google OAuth client id for GIS (the personalized "Continue as
+     * <name>" One Tap / renderButton path). In the elvix monorepo this is the
+     * build-time `NEXT_PUBLIC_GOOGLE_CLIENT_ID`; for the published SDK it
+     * arrives per-app on the bootstrap envelope. When absent, the Google
+     * factor degrades to the static redirect anchor (which uses elvix's
+     * server-side client id via `/api/auth/google/start`).
+     */
+    googleClientId?: string;
     signinGate: "public" | "private_beta" | "closed";
     archivedAt: string | null;
     /**
@@ -163,18 +180,53 @@ type ElvixSignInResultErr = {
     error: string;
     message?: string;
 };
-type ElvixSignInResult = ElvixSignInResultOk | ElvixSignInResultErr;
+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;
@@ -204,7 +256,7 @@ declare function ElvixProvider({ clientId, theme, brand, baseUrl, children, clas
  * calls `router.push` itself.
  */
 declare function ElvixSignIn({ onResult, redirectAfterSignIn, copy: copyProp, className, width, height, minWidth, maxWidth, minHeight, maxHeight, }: {
-    onResult?: (r: ElvixSignInResult) => void;
+    onResult?: (r: ElvixSignInResult$1) => void;
     /** Default redirect target on success when the server doesn't echo one. */
     redirectAfterSignIn?: string;
     /**
@@ -217,42 +269,182 @@ declare function ElvixSignIn({ onResult, redirectAfterSignIn, copy: copyProp, cl
 } & ElvixSizeProps): react_jsx_runtime.JSX.Element;
 
 /**
- * `<ElvixSignInForm>` — the polished, fully-styled sign-in surface a
- * customer drops onto their own app.
+ * Public ResponseDto shape the SDK surfaces to `onResult` listeners.
+ * Mirrors the `{ ok: true | false, ... }` envelope every elvix API
+ * route returns via `withErrorHandling`. Customers branch on `ok`.
+ */
+type ElvixSignInResult = {
+    ok: true;
+    redirect?: string;
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+    status?: number;
+};
+declare const Mode: {
+    readonly PREVIEW: "preview";
+    readonly INTERACTIVE: "interactive";
+};
+type Mode = (typeof Mode)[keyof typeof Mode];
+declare const Intent: {
+    readonly CONSOLE: "console";
+    readonly ACCOUNT: "account";
+    readonly APP: "app";
+};
+type Intent = (typeof Intent)[keyof typeof Intent];
+declare const Layout: {
+    readonly CENTERED: "centered";
+    readonly LEFT: "left";
+    readonly BANNER: "banner";
+};
+type Layout = (typeof Layout)[keyof typeof Layout];
+declare const SocialLayout: {
+    readonly STACKED: "stacked";
+    readonly GRID: "grid";
+};
+type SocialLayout = (typeof SocialLayout)[keyof typeof SocialLayout];
+declare const Presentation: {
+    readonly CARD: "card";
+    readonly DRAWER: "drawer";
+    readonly MODAL: "modal";
+};
+type Presentation = (typeof Presentation)[keyof typeof Presentation];
+declare const Theme: {
+    readonly LIGHT: "light";
+    readonly DARK: "dark";
+    readonly AUTO: "auto";
+};
+type Theme = (typeof Theme)[keyof typeof Theme];
+declare const SignInVerb: {
+    readonly SIGNIN: "signin";
+    readonly LOGIN: "login";
+};
+type SignInVerb = (typeof SignInVerb)[keyof typeof SignInVerb];
+/**
+ * One auth surface to rule them all. Same component renders:
  *
- * Where `<ElvixSignIn>` is the bare-bones flow (class-hooked, host paints
- * it), this is the finished card: rounded logo tile, "Sign in to {app}"
- * heading, "Continue with Google", an OR divider, the email→code OTP
- * flow, a legal footer, and a "Secured by elvix" badge. It ships with
- * **inline styles only** — no host CSS required, so it looks right the
- * moment it mounts on any origin.
+ *   - The live preview inside the Console (Create app + Sign-in configure).
+ *     mode="preview" → all controls disabled, just visual.
  *
- * Cross-origin correct: OTP start/verify pick credentials from
- * `isSameOrigin(baseUrl)` exactly like `<ElvixSignIn>`; on a third-party
- * origin the session token comes back in the response body and is stored
- * via `setElvixToken`. Google is a top-level redirect.
+ *   - The actual hosted sign-in at /sign-in/<clientId> for any customer app.
+ *     mode="interactive" + intent="app:<clientId>" → real flows.
  *
- * Reads enabled methods + branding from the Console-configured bootstrap
- * envelope (`<ElvixProvider clientId>` must be an ancestor). Renders only
- * the factors the Console turned on; never invents UI it denied.
+ *   - The elvix Console's own sign-in at /sign-in/console.
+ *     mode="interactive" + intent="console" → dogfoods our own auth.
  *
- * `onResult({ ok, ... })` fires on success AND every failure, mirroring
- * `<ElvixSignIn>`. The component never navigates the host itself.
+ *   - The account surface at /sign-in/account.
+ *     mode="interactive" + intent="account".
+ *
+ * Sign-in = Sign-up. There's no separate signup route. If you don't exist
+ * yet, the first successful auth creates you.
  */
-type ElvixSignInFormProps = {
-    /** Fires on every terminal outcome — success and failure — like `<ElvixSignIn>`. */
-    onResult?: (r: ElvixSignInResult) => void;
-    /** Default redirect target on success when the server doesn't echo one. */
-    redirectAfterSignIn?: string;
+type AuthFormProps = {
     /**
-     * Thin per-embed copy override. The primary way to edit copy is the elvix
-     * Console (served live in the bootstrap `strings`); this prop just lets a
-     * single embed tweak a string or two without a Console change.
+     * "interactive" (default) hits real auth endpoints.
+     * "preview" renders the surface read-only — every CTA paints but
+     * never makes a request. Console live-preview uses this.
      */
-    copy?: Partial<ElvixCopy>;
-    className?: string;
-} & /** Sizing — applied to the card root inline style (SDK components are sizable). */ ElvixSizeProps;
-declare function ElvixSignInForm({ onResult, redirectAfterSignIn, copy: copyProp, className, minWidth, maxWidth, minHeight, maxHeight, width, height, }: ElvixSignInFormProps): react_jsx_runtime.JSX.Element;
+    mode?: Mode;
+    /**
+     * App display name. Optional when `<ElvixProvider clientId>` is
+     * mounted — the provider fetches it from the Console-configured
+     * Application row. Explicit prop wins (Console passes its unsaved
+     * live state here).
+     */
+    appName?: string;
+    logoUrl?: string | null;
+    /** Optional dark-mode variant. Used when `theme="dark"`, otherwise we
+     *  show the same logoUrl in both themes. */
+    logoUrlDark?: string | null;
+    /** Optional pre-rendered logo node. Wins over logoUrl + letter fallback. */
+    logoNode?: React.ReactNode;
+    brandColor?: string;
+    /** Foreground colour painted on top of brandColor (CTA text/icons). */
+    onBrandColor?: string;
+    methodGoogle?: boolean;
+    methodEmailOtp?: boolean;
+    methodPasskey?: boolean;
+    methodUsername?: boolean;
+    privacyPolicyUrl?: string | null;
+    termsOfServiceUrl?: string | null;
+    framed?: boolean;
+    /** Used in interactive mode to route auth requests. */
+    intent?: Intent;
+    /** For intent="app": the Application client_id. */
+    clientId?: string;
+    /** If set, the logo becomes a clickable link to this URL (the app's website). */
+    websiteUrl?: string | null;
+    /** Visual layout. Three variants today. */
+    layout?: Layout;
+    /** Social button arrangement: stacked rows (default) or 2-up grid. */
+    socialLayout?: SocialLayout;
+    /** Surrounding chrome — card / drawer (bottom sheet) / modal overlay. */
+    presentation?: Presentation;
+    /** Theme override for the form's surface tokens. */
+    theme?: Theme;
+    /** Hide the built-in header (logo + "Sign in to X" title + subtitle). */
+    showHeader?: boolean;
+    /** Which verb the customer wants on the CTA + heading. Some brands
+     *  prefer "Log in" (banks, B2B legacy); SaaS defaults to "Sign in". */
+    signInVerb?: SignInVerb;
+    /** Strip card bg + border + shadow so the form blends into its host. */
+    transparentBg?: boolean;
+    /** Optional node rendered directly below the "Pick how you want to
+     *  continue" subtitle. Used for gate-state badges ("Private beta",
+     *  "Closed signups") so they sit inline with the form instead of
+     *  competing as a separate surface above the card. */
+    belowHeading?: React.ReactNode;
+    /** Optional pre-rendered node injected just under the methods, on
+     *  the way to the "Secured by elvix" chip. Used for the
+     *  "Inform me when it goes public" + "Request access" text-links
+     *  shown on gated hosted surfaces. */
+    belowMethods?: React.ReactNode;
+    /** Per-app Google Identity Services config. When set + `methodGoogle`
+     *  is on + we're in interactive mode + a `googleClientId` is available,
+     *  the ElvixSignInForm loads the GIS client lib and applies One Tap /
+     *  Auto-select / FedCM / popup ux_mode based on each flag. Falls back to
+     *  the plain redirect-OAuth anchor otherwise. */
+    googleConfig?: {
+        oneTap?: boolean;
+        autoSelect?: boolean;
+        popup?: boolean;
+        fedcm?: boolean;
+        hostedDomain?: string;
+    };
+    /** Public Google OAuth client id for the GIS personalized button. In the
+     *  elvix monorepo this is the build-time `NEXT_PUBLIC_GOOGLE_CLIENT_ID`;
+     *  the SDK reads it off the bootstrap envelope (`googleClientId`). When
+     *  absent, the Google factor degrades to the static redirect anchor. */
+    googleClientId?: string;
+    /**
+     * Fires after a successful sign-in (OTP, Google, Passkey) — BEFORE
+     * the default redirect runs. When provided, the form will NOT
+     * navigate; the host owns post-auth routing. Use this to keep an
+     * embedded surface (Drawer/Modal/Card) in place after auth and let
+     * the host call `router.push()` itself.
+     *
+     * Call `GET /api/me` from the host to fetch the authenticated user.
+     * The v2 SDK will surface user details directly in the payload.
+     */
+    onAuthenticated?: (result: {
+        ok: true;
+        redirect?: string;
+        token?: string;
+    }) => void;
+    /**
+     * Fires on every terminal outcome: success AND every error path
+     * (invalid OTP, expired challenge, rate-limited, network blip,
+     * passkey failure). Mirrors the ResponseDto shape the rest of the
+     * elvix API surfaces, so the customer branches on `ok` the same
+     * way they would for a `/api/v1/verify` call.
+     *
+     * Both `onResult` and `onAuthenticated` may be set. `onResult` fires
+     * regardless; `onAuthenticated` only on success (legacy contract).
+     */
+    onResult?: (result: ElvixSignInResult) => void;
+};
+declare function ElvixSignInForm(props: AuthFormProps): react_jsx_runtime.JSX.Element;
 
 type ElvixSignInButtonSize = "sm" | "md" | "lg";
 type ElvixSignInButtonTheme = "light" | "dark" | "auto";
@@ -278,7 +470,7 @@ type ElvixSignInButtonProps = {
     mode?: ElvixSignInButtonMode;
     onClick?: () => void;
     /** Terminal outcome of mode="embed": success (with token) or error. */
-    onResult?: (result: ElvixSignInResult) => void;
+    onResult?: (result: ElvixSignInResult$1) => void;
 } & /**
  * Dimensional sizing (width/height/min/max), additive to the `size` preset.
  * Merged last into the root element so an explicit width/height wins.
@@ -315,6 +507,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[];
@@ -343,116 +547,497 @@ declare function ElvixLifecycleWatcher({ baseUrl, pollMs, onSignedOut, }: {
     onSignedOut?: (reason: string) => void;
 }): 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, 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 };