@edgespark/web 0.0.0-beta.4ec283e

package/dist/auth-ui/types.d.ts

@@ -0,0 +1,202 @@
+import { AuthSession, AuthUser } from '../auth/types';
+import { EdgeSparkAuthError } from '../errors';
+import { RedirectTarget } from '../redirect';
+import { DeepPartial } from '../shared/types';
+import { AuthUIAppearance } from './appearance';
+import { OneTapPromptHandle, PromptGoogleOneTapOptions } from './prompt-google-one-tap';
+export type { OneTapPromptHandle, PromptGoogleOneTapOptions } from './prompt-google-one-tap';
+/** Sign-in or sign-up completed with an authenticated session. */
+export type AuthenticatedAuthSuccessEvent = {
+    action: "sign-in";
+    user: AuthUser;
+    session: AuthSession;
+} | {
+    action: "sign-up";
+    user: AuthUser;
+    session: AuthSession;
+};
+/** Password was reset. No session — the user must sign in again. */
+export interface PasswordResetSuccessEvent {
+    action: "password-reset";
+    user: null;
+    session: null;
+}
+/**
+ * Payload emitted by `onSuccess` after a managed auth flow completes.
+ *
+ * Switch on `event.action` to narrow `user` and `session`:
+ * - `"sign-in"` / `"sign-up"` → `user: AuthUser`, `session: AuthSession`
+ * - `"password-reset"` → `user: null`, `session: null`
+ */
+export type AuthSuccessEvent = AuthenticatedAuthSuccessEvent | PasswordResetSuccessEvent;
+export interface AuthUILabels {
+    common: {
+        loading: string;
+        redirecting: string;
+        backToSignIn: string;
+    };
+    signIn: {
+        title: string;
+        subtitle: string;
+        emailLabel: string;
+        emailPlaceholder?: string;
+        codePlaceholder?: string;
+        sendingCode?: string;
+        signingIn?: string;
+        passwordLabel: string;
+        codeLabel?: string;
+        submitButton: string;
+        sendCodeButton?: string;
+        verifyCodeButton?: string;
+        resendCodeButton?: string;
+        resendCountdown?: string;
+        passwordTab?: string;
+        codeTab?: string;
+        phoneTab?: string;
+        phoneLabel?: string;
+        phonePlaceholder?: string;
+        phoneCodePlaceholder?: string;
+        forgotPassword: string;
+        switchToSignUp: string;
+        signUpPrompt: string;
+    };
+    signUp: {
+        title: string;
+        subtitle: string;
+        nameLabel: string;
+        emailLabel: string;
+        passwordLabel: string;
+        confirmPasswordLabel: string;
+        submitButton: string;
+        switchToSignIn: string;
+        signInPrompt: string;
+    };
+    verifyEmail: {
+        title: string;
+        subtitle: string;
+        sentToLabel: string;
+        resendButton: string;
+        resendCountdown: string;
+        changeEmailButton: string;
+    };
+    forgotPassword: {
+        title: string;
+        subtitle: string;
+        emailLabel: string;
+        submitButton: string;
+    };
+    resetPassword: {
+        title: string;
+        subtitle: string;
+        codeLabel: string;
+        newPasswordLabel: string;
+        confirmPasswordLabel: string;
+        submitButton: string;
+        resendCodeButton: string;
+        resendCountdown: string;
+    };
+    oauth: {
+        dividerText: string;
+        continueWith: string;
+        /** Use {provider} for the provider display name. */
+        redirecting?: string;
+    };
+    errors: {
+        invalidEmail: string;
+        requiredField: string;
+        passwordTooShort: string;
+        passwordMismatch: string;
+        invalidCode: string;
+        invalidPhone?: string;
+        smsRateLimited?: string;
+        smsSendFailed?: string;
+        generic: string;
+    };
+}
+export type AuthUILabelOverrides = DeepPartial<AuthUILabels>;
+/** Sign-in form methods: email + password, email code, or SMS code. */
+export type AuthUISignInMethod = "password" | "otp" | "phone";
+interface BaseAuthUIOptions {
+    onError?: (error: EdgeSparkAuthError) => void;
+    labels?: AuthUILabelOverrides;
+    /**
+     * Limits which sign-in form methods are offered, e.g. to show SMS sign-in
+     * only to some visitors. Methods the project's auth config does not enable
+     * are never shown. Omit to offer every enabled method.
+     */
+    signInMethods?: readonly AuthUISignInMethod[];
+    /**
+     * Optional, constrained visual customization for the managed auth UI.
+     *
+     * This is intentionally smaller than the headless auth path. Use
+     * `client.auth` when the app needs full UI ownership.
+     */
+    appearance?: AuthUIAppearance;
+}
+/**
+ * Redirect mode — use when the auth UI is a full-page login gate.
+ *
+ * After successful auth the SDK navigates to `redirectTo` automatically.
+ * This is the common case: dedicated `/login` page → redirect to `/dashboard`.
+ *
+ * `onSuccess` is optional and fires *before* the redirect (useful for analytics).
+ */
+export interface RedirectAuthUIOptions extends BaseAuthUIOptions {
+    redirectTo: RedirectTarget;
+    onSuccess?: (event: AuthSuccessEvent) => void;
+}
+/**
+ * Controlled mode — use when the app owns what happens after auth.
+ *
+ * The SDK will not navigate. Instead, `onSuccess` fires with the auth event
+ * and the app decides the next step (close a modal, update state, navigate
+ * programmatically via a router, etc.).
+ *
+ * Use this for: modals, embedded auth widgets, SPA routing, onboarding flows.
+ */
+export interface ControlledAuthUIOptions extends BaseAuthUIOptions {
+    onSuccess: (event: AuthSuccessEvent) => void;
+    redirectTo?: never;
+}
+/**
+ * Two post-auth strategies — pick one:
+ *
+ * - **Redirect mode** (`{ redirectTo }`) — SDK navigates after auth.
+ *   Best for dedicated login pages.
+ *
+ * - **Controlled mode** (`{ onSuccess }`) — app handles post-auth behavior.
+ *   Best for modals, embedded widgets, or SPA routing.
+ */
+export type MountAuthUIOptions = RedirectAuthUIOptions | ControlledAuthUIOptions;
+export interface MountedAuthUI {
+    /**
+     * Removes the mounted UI and clears internal timers/listeners.
+     */
+    destroy(): void;
+}
+export interface EdgeSparkAuthUI {
+    /**
+     * Mounts the managed auth UI into a container element.
+     *
+     * Pass `redirectTo` for the common login-page case, or `onSuccess` when the
+     * surrounding app wants to control routing/state after auth completes.
+     */
+    mount(container: HTMLElement, options: MountAuthUIOptions): MountedAuthUI;
+    /**
+     * Triggers a Google One Tap prompt. Calling the function is the opt-in —
+     * there is no separate server config or option flag.
+     *
+     * The prompt shows only when Google is fully wired server-side (the
+     * project's `auth-config.yaml` enables Google with resolvable credentials).
+     * Otherwise the call logs a clear error to the console and returns an
+     * inert handle.
+     *
+     * @example
+     * useEffect(() => {
+     *   if (session) return;
+     *   const prompt = client.authUI.promptGoogleOneTap();
+     *   return () => prompt.cancel();
+     * }, [session]);
+     */
+    promptGoogleOneTap(options?: PromptGoogleOneTapOptions): OneTapPromptHandle;
+}

package/dist/browser.d.ts

@@ -0,0 +1,2 @@
+export declare function assertBrowserRuntime(): void;
+export declare function getBrowserOrigin(): string;

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+import { EdgeSparkApi } from './api/types';
+import { EdgeSparkAuth } from './auth/types';
+import { EdgeSparkAuthUI } from './auth-ui';
+export interface EdgeSparkClient {
+    /**
+       * Headless auth client with a better-auth-aligned API shape, plus a small
+       * set of EdgeSpark session helpers:
+       *
+       * - `requireSession()` — resolves or throws, for route guards
+       * - `onSessionChange()` — hydration-safe session observer
+       *
+       * Standard auth methods such as `signIn.email`, `signIn.social`,
+       * `signUp.email`, `signOut`, and `getSession` remain available on the same
+       * familiar shape.
+       *
+       * Some upstream better-auth methods may still be intentionally unsupported
+       * by the current EdgeSpark platform capability set. Those methods fail fast
+       * with `UNSUPPORTED_AUTH_METHOD` instead of deferring to a platform 400/404.
+     */
+    auth: EdgeSparkAuth;
+    /**
+     * Same-origin fetch wrapper for app APIs.
+     *
+     * Always sends cookie credentials. Rejects cross-origin URLs.
+     */
+    api: EdgeSparkApi;
+    /**
+     * Managed auth UI for login, sign-up, verification, and password reset flows.
+     *
+     * Mount with `{ redirectTo }` for login pages, or `{ onSuccess }` for
+     * modals and SPA routing.
+     */
+    authUI: EdgeSparkAuthUI;
+}
+/**
+ * Creates the EdgeSpark browser client.
+ *
+ * The v2 SDK is intentionally zero-config:
+ * - current page origin is always used
+ * - cookie credentials are always enabled
+ * - auth routes stay internal
+ */
+export declare function createEdgeSpark(): EdgeSparkClient;

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/** Base error class for all EdgeSpark SDK errors. Use `instanceof` to catch. */
+export declare class EdgeSparkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Programmer mistake: bad options, invalid container, cross-origin fetch, etc. */
+export declare class EdgeSparkConfigError extends EdgeSparkError {
+    constructor(message: string);
+}
+/** Called outside a browser (SSR, Node, tests without DOM). */
+export declare class EdgeSparkRuntimeError extends EdgeSparkError {
+    constructor(message: string);
+}
+/** Auth operation failed (sign-in rejected, session missing, etc.). */
+export declare class EdgeSparkAuthError extends EdgeSparkError {
+    readonly cause?: unknown;
+    readonly status?: number;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+        status?: number;
+    });
+}
+/**
+ * Normalize an unknown thrown value into an {@link EdgeSparkAuthError}.
+ *
+ * Already-normalized instances pass through unchanged. Objects with
+ * `message`/`code`/`status` fields are preserved. Plain strings become
+ * the error message. Everything else falls back to the caller-supplied
+ * defaults.
+ */
+export declare function normalizeToAuthError(error: unknown, fallbackMessage?: string, fallbackCode?: string): EdgeSparkAuthError;