@edgespark/web 0.0.1-beta.0

package/README.md

@@ -0,0 +1,130 @@
+# `@edgespark/web`
+
+Parallel rewrite of the EdgeSpark browser SDK.
+
+This package is intentionally:
+
+- browser-only
+- same-origin only
+- cookie-session only
+- zero-config
+- optimized for agent-written code
+
+## Use in this repo
+
+```bash
+pnpm install
+pnpm --filter @edgespark/web build
+```
+
+## Quick start
+
+```ts
+import { createEdgeSpark } from "@edgespark/web";
+import "@edgespark/web/styles.css";
+
+const es = createEdgeSpark();
+const container = document.getElementById("auth")!;
+
+es.authUI.mount(container, {
+  redirectTo: "/dashboard",
+});
+```
+
+## Public surface
+
+```ts
+const es = createEdgeSpark();
+const container = document.getElementById("auth")!;
+
+es.auth;
+es.api.fetch("/api/todos");
+es.authUI.mount(container, { redirectTo: "/dashboard" });
+```
+
+### `auth`
+
+`es.auth` is the better-auth client, with two small EdgeSpark additions:
+
+```ts
+const session = await es.auth.requireSession();
+const unsubscribe = es.auth.onSessionChange((session) => {
+  console.log(session?.user.email ?? "signed out");
+});
+```
+
+Use the upstream better-auth auth methods directly:
+
+```ts
+await es.auth.signIn.email({ email, password });
+await es.auth.signUp.email({ name, email, password });
+await es.auth.signOut();
+await es.auth.getSession();
+```
+
+### `api`
+
+`es.api.fetch(...)` is the same-origin fetch wrapper for authenticated app requests.
+
+```ts
+const response = await es.api.fetch("/api/todos");
+const todos = await response.json();
+```
+
+The wrapper always uses cookie credentials, rejects cross-origin URLs, and does not accept a `credentials` override in its `init` type.
+
+### `authUI`
+
+The managed auth UI supports exactly two post-auth strategies.
+
+#### Redirect mode
+
+```ts
+const container = document.getElementById("auth")!;
+
+const ui = es.authUI.mount(container, {
+  redirectTo: "/dashboard",
+});
+```
+
+#### Controlled mode
+
+```ts
+const container = document.getElementById("auth")!;
+
+const ui = es.authUI.mount(container, {
+  onSuccess(event) {
+    if (event.action === "password-reset") {
+      return;
+    }
+
+    window.location.assign("/dashboard");
+  },
+});
+```
+
+`ui.destroy()` removes the mounted UI and clears timers/listeners.
+
+Password reset has one special rule:
+
+- in controlled mode, `onSuccess({ action: "password-reset" })` fires and the caller owns the next step
+- in redirect mode, the UI returns to sign-in with a success notice instead of redirecting to an authenticated page
+
+## Flows covered by the managed UI
+
+- email/password sign-in
+- email/password sign-up
+- OAuth sign-in
+- email verification instructions + resend
+- forgot password
+- reset password with email OTP
+
+The forgot-password path only appears when the project config enables email-OTP password reset.
+
+## Design notes
+
+- `createEdgeSpark()` takes no options
+- current page origin is used internally
+- auth base path is internal
+- credentials mode is internal
+- local dev with separate web/backend ports should use a dev proxy so the browser still sees same-origin requests

package/auth/styles/styles.css

@@ -0,0 +1,245 @@
+[data-edgespark-auth] {
+  --edgespark-auth-bg: #ffffff;
+  --edgespark-auth-bg-muted: #f7f7f8;
+  --edgespark-auth-border: rgba(15, 23, 42, 0.08);
+  --edgespark-auth-text: #111827;
+  --edgespark-auth-text-muted: #6b7280;
+  --edgespark-auth-primary: #0f766e;
+  --edgespark-auth-primary-hover: #115e59;
+  --edgespark-auth-error: #b91c1c;
+  --edgespark-auth-info: #0f766e;
+  --edgespark-auth-radius-card: 20px;
+  --edgespark-auth-radius-control: 12px;
+  --edgespark-auth-shadow: 0 24px 60px rgba(15, 23, 42, 0.08);
+  --edgespark-auth-font: "IBM Plex Sans", "Inter", ui-sans-serif, system-ui, sans-serif;
+  color: var(--edgespark-auth-text);
+  font-family: var(--edgespark-auth-font);
+}
+
+[data-edgespark-auth] *,
+[data-edgespark-auth] *::before,
+[data-edgespark-auth] *::after {
+  box-sizing: border-box;
+}
+
+.edgespark-auth__shell {
+  width: 100%;
+}
+
+.edgespark-auth__card {
+  display: grid;
+  gap: 16px;
+  width: 100%;
+  max-width: 420px;
+  padding: 24px;
+  border: 1px solid var(--edgespark-auth-border);
+  border-radius: var(--edgespark-auth-radius-card);
+  background: linear-gradient(180deg, #ffffff 0%, #fcfcfc 100%);
+  box-shadow: var(--edgespark-auth-shadow);
+}
+
+.edgespark-auth__section,
+.edgespark-auth__form,
+.edgespark-auth__stack {
+  display: grid;
+  gap: 14px;
+}
+
+.edgespark-auth__header {
+  display: grid;
+  gap: 8px;
+}
+
+.edgespark-auth__title {
+  margin: 0;
+  font-size: 1.75rem;
+  line-height: 1.1;
+  font-weight: 700;
+  letter-spacing: -0.03em;
+}
+
+.edgespark-auth__copy,
+.edgespark-auth__meta {
+  margin: 0;
+  color: var(--edgespark-auth-text-muted);
+  font-size: 0.95rem;
+  line-height: 1.5;
+}
+
+.edgespark-auth__field {
+  display: grid;
+  gap: 8px;
+}
+
+.edgespark-auth__label {
+  font-size: 0.9rem;
+  font-weight: 600;
+}
+
+.edgespark-auth__input {
+  width: 100%;
+  min-height: 48px;
+  padding: 0 14px;
+  border: 1px solid var(--edgespark-auth-border);
+  border-radius: var(--edgespark-auth-radius-control);
+  background: var(--edgespark-auth-bg);
+  color: var(--edgespark-auth-text);
+  font: inherit;
+}
+
+.edgespark-auth__input:focus {
+  outline: 2px solid color-mix(in srgb, var(--edgespark-auth-primary) 35%, transparent);
+  outline-offset: 1px;
+  border-color: var(--edgespark-auth-primary);
+}
+
+.edgespark-auth__button,
+.edgespark-auth__link {
+  font: inherit;
+}
+
+.edgespark-auth__button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 48px;
+  padding: 0 16px;
+  border-radius: 999px;
+  border: 1px solid transparent;
+  cursor: pointer;
+  transition: background-color 120ms ease, border-color 120ms ease, color 120ms ease, opacity 120ms ease;
+}
+
+.edgespark-auth__button:disabled,
+.edgespark-auth__link:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.edgespark-auth__button--primary {
+  background: var(--edgespark-auth-primary);
+  color: #ffffff;
+}
+
+.edgespark-auth__button--primary:hover:not(:disabled) {
+  background: var(--edgespark-auth-primary-hover);
+}
+
+.edgespark-auth__button--secondary {
+  border-color: var(--edgespark-auth-border);
+  background: var(--edgespark-auth-bg);
+  color: var(--edgespark-auth-text);
+}
+
+.edgespark-auth__button--secondary:hover:not(:disabled) {
+  background: var(--edgespark-auth-bg-muted);
+}
+
+.edgespark-auth__actions {
+  display: grid;
+  gap: 10px;
+}
+
+.edgespark-auth__link {
+  justify-self: start;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: var(--edgespark-auth-primary);
+  cursor: pointer;
+}
+
+.edgespark-auth__divider {
+  position: relative;
+  text-align: center;
+  color: var(--edgespark-auth-text-muted);
+  font-size: 0.85rem;
+}
+
+.edgespark-auth__divider::before {
+  content: "";
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: 50%;
+  border-top: 1px solid var(--edgespark-auth-border);
+}
+
+.edgespark-auth__divider span {
+  position: relative;
+  padding: 0 10px;
+  background: var(--edgespark-auth-bg);
+}
+
+.edgespark-auth__status {
+  padding: 12px 14px;
+  border-radius: 14px;
+  font-size: 0.92rem;
+  line-height: 1.5;
+}
+
+.edgespark-auth__status--error {
+  color: var(--edgespark-auth-error);
+  background: color-mix(in srgb, var(--edgespark-auth-error) 10%, #ffffff);
+}
+
+.edgespark-auth__status--info {
+  color: var(--edgespark-auth-info);
+  background: color-mix(in srgb, var(--edgespark-auth-info) 10%, #ffffff);
+}
+
+.edgespark-auth__status--muted {
+  color: var(--edgespark-auth-text-muted);
+  background: var(--edgespark-auth-bg-muted);
+}
+
+.edgespark-auth__iframe-modal {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background: rgba(15, 23, 42, 0.22);
+}
+
+.edgespark-auth__iframe-modal-card {
+  position: relative;
+  display: grid;
+  gap: 16px;
+  width: min(520px, 100%);
+  padding: 28px;
+  border-radius: 24px;
+  background: #ffffff;
+  box-shadow: 0 24px 60px rgba(15, 23, 42, 0.18);
+}
+
+.edgespark-auth__iframe-modal-close {
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  width: 36px;
+  height: 36px;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--edgespark-auth-text-muted);
+  font-size: 1.5rem;
+  cursor: pointer;
+}
+
+.edgespark-auth__iframe-modal-close:hover {
+  background: var(--edgespark-auth-bg-muted);
+}
+
+@media (max-width: 480px) {
+  .edgespark-auth__card {
+    padding: 18px;
+    border-radius: 16px;
+  }
+
+  .edgespark-auth__title {
+    font-size: 1.45rem;
+  }
+}

package/dist/api/fetch.d.ts

@@ -0,0 +1,8 @@
+import { EdgeSparkApi } from './types';
+/**
+ * Creates the API module used by EdgeSpark apps.
+ *
+ * The wrapper keeps cookie credentials enabled and rejects cross-origin URLs so
+ * the SDK stays honest about its same-origin product boundary.
+ */
+export declare function createApiModule(): EdgeSparkApi;

package/dist/api/types.d.ts

@@ -0,0 +1,13 @@
+export type EdgeSparkRequestInit = Omit<RequestInit, "credentials">;
+/**
+ * Same-origin fetch wrapper for authenticated app requests.
+ */
+export interface EdgeSparkApi {
+    /**
+     * Same-origin `fetch` with cookie credentials always enabled.
+     *
+     * `credentials` is intentionally omitted from the accepted init shape because
+     * the SDK never allows callers to disable cookie auth.
+     */
+    fetch(input: RequestInfo | URL, init?: EdgeSparkRequestInit): Promise<Response>;
+}

package/dist/auth/create-auth.d.ts

@@ -0,0 +1,17 @@
+import { BetterAuthClientInstance, EdgeSparkAuth } from './types';
+export declare const AUTH_BASE_PATH: "/api/_es/auth";
+export declare function syncEdgeSparkAuthSession(authClient: BetterAuthClientInstance): Promise<void>;
+/**
+ * Creates the headless auth module.
+ *
+ * This intentionally mirrors better-auth so agents can rely on upstream API
+ * knowledge instead of learning a second parallel auth surface.
+ */
+export declare function createEdgeSparkAuth(): EdgeSparkAuth;
+/**
+ * Creates the internal auth client used by the managed UI.
+ *
+ * Redirect handling is intentionally disabled here so `authUI` can own
+ * callback timing, loading state, and post-auth navigation semantics.
+ */
+export declare function createManagedAuthUIClient(): BetterAuthClientInstance;

package/dist/auth/types.d.ts

@@ -0,0 +1,55 @@
+import { createAuthClient } from 'better-auth/client';
+/**
+ * Direct better-auth client instance returned by createAuthClient().
+ */
+export type BetterAuthClientInstance = ReturnType<typeof createAuthClient>;
+export type SessionResult = Awaited<ReturnType<BetterAuthClientInstance["getSession"]>>;
+export type AuthSession = NonNullable<SessionResult["data"]>;
+export type AuthUser = AuthSession["user"];
+export type SessionChangeCallback = (session: AuthSession | null) => void;
+export interface AuthEndpointError {
+    code?: string;
+    message?: string;
+    status?: number;
+}
+export interface AuthEndpointResult<TData = unknown> {
+    data?: TData | null;
+    error?: AuthEndpointError | null;
+}
+/**
+ * EdgeSpark keeps auth primitive usage aligned with better-auth.
+ *
+ * All better-auth client methods work directly.  EdgeSpark adds three
+ * small conveniences on top: `requireSession`, `onSessionChange`, and
+ * a wrapped `signOut` that guarantees same-tab session invalidation.
+ */
+export type EdgeSparkAuth = BetterAuthClientInstance & {
+    /**
+     * Resolves with the current session, or throws when the browser is not authenticated.
+     *
+     * Use this for route guards and other flows where nullable session checks add noise.
+     */
+    requireSession(): Promise<AuthSession>;
+    /**
+     * Subscribes to session changes for the current tab.
+     *
+     * The first emission is **hydration-safe**: it waits for the initial server
+     * session check to complete before firing, so subscribers never receive a
+     * premature `null` that looks like "not authenticated" while the cookie
+     * session is still being verified.
+     *
+     * After the initial emission, every session atom update is forwarded
+     * immediately (sign-in from another tab, sign-out, token refresh, etc.).
+     *
+     * Returns an unsubscribe function.
+     */
+    onSessionChange(callback: SessionChangeCallback): () => void;
+    /**
+     * Signs out and invalidates the session for the current tab.
+     *
+     * This wraps better-auth's `signOut` and additionally forces the session
+     * atom to refetch, ensuring `onSessionChange` subscribers are notified
+     * synchronously after the call completes.
+     */
+    signOut(...args: Parameters<BetterAuthClientInstance["signOut"]>): ReturnType<BetterAuthClientInstance["signOut"]>;
+};

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

@@ -0,0 +1,80 @@
+import { BetterAuthClientInstance } from '../auth/types';
+import { NormalizedAuthUIConfig } from './config';
+import { MountAuthUIOptions, MountedAuthUI } from './types';
+interface ManagedAuthUIRuntimeOptions {
+    syncPublicSession?: () => Promise<void> | void;
+}
+/**
+ * Internal managed auth UI implementation.
+ *
+ * The public API only exposes `authUI.mount(...)`; this class owns the DOM,
+ * form flows, and lifecycle.
+ */
+export declare class ManagedAuthUI implements MountedAuthUI {
+    private readonly container;
+    private readonly auth;
+    private readonly options;
+    private readonly loadConfig;
+    private readonly runtimeOptions?;
+    private readonly labels;
+    private readonly root;
+    private readonly state;
+    private destroyed;
+    private terminalActionInProgress;
+    private config;
+    private countdownUntil;
+    private countdownTimer;
+    private pendingFocusSnapshot;
+    private focusRestoreTimer;
+    private verificationCompletionAction;
+    constructor(container: HTMLElement, auth: BetterAuthClientInstance, options: MountAuthUIOptions, loadConfig: () => Promise<NormalizedAuthUIConfig>, runtimeOptions?: ManagedAuthUIRuntimeOptions | undefined);
+    destroy(): void;
+    private initialize;
+    private render;
+    private renderLoading;
+    private renderStatus;
+    private renderCurrentView;
+    private renderSignInView;
+    private renderSignUpView;
+    private renderVerifyEmailView;
+    private renderForgotPasswordView;
+    private renderResetPasswordView;
+    private renderOAuthProviders;
+    private renderInput;
+    private bindDOM;
+    private switchView;
+    private handleSignIn;
+    private handleSignUp;
+    private handleOAuthSignIn;
+    private handleForgotPassword;
+    private resendResetCode;
+    private handleResetPassword;
+    private resendVerificationEmail;
+    private sendVerificationEmail;
+    private completeAuth;
+    private resolveAuthCompletionData;
+    private completePasswordReset;
+    private handleExistingSessionOnMount;
+    private runAction;
+    private maybeHandleVerificationRequired;
+    private handleVerificationEmailSent;
+    private handleError;
+    private failValidation;
+    private getManagedReturnURL;
+    private consumeManagedReturnContext;
+    private startCountdown;
+    private clearCountdown;
+    private captureFocusSnapshot;
+    private scheduleFocusRestore;
+    private clearFocusRestoreTimer;
+    private passwordResetEndpoints;
+    private extractRedirectURL;
+    private extractUser;
+    private canUsePasswordResetEmailOtp;
+    private handleSessionlessManagedReturn;
+    private isCountdownActive;
+    private getCountdownSecondsRemaining;
+    private countdownText;
+    private escape;
+}
+export {};

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

@@ -0,0 +1,33 @@
+export type OAuthProviderId = "google" | "apple" | "microsoft" | "github" | "gitlab" | "discord";
+interface OAuthProviderBlock {
+    enabled?: boolean;
+}
+interface ProviderEmailPassword {
+    enabled?: boolean;
+    config?: {
+        minPasswordLength?: number;
+        requireEmailVerification?: boolean;
+        requirePasswordResetEmailVerification?: boolean;
+    };
+}
+interface AuthConfigResponse {
+    disableSignUp?: boolean;
+    providerEmailPassword?: ProviderEmailPassword;
+    providerGoogle?: OAuthProviderBlock;
+    providerApple?: OAuthProviderBlock;
+    providerMicrosoft?: OAuthProviderBlock;
+    providerGithub?: OAuthProviderBlock;
+    providerGitlab?: OAuthProviderBlock;
+    providerDiscord?: OAuthProviderBlock;
+}
+export interface NormalizedAuthUIConfig {
+    disableSignUp: boolean;
+    emailPasswordEnabled: boolean;
+    minPasswordLength: number;
+    requireEmailVerification: boolean;
+    passwordResetEmailOtpEnabled: boolean;
+    oauthProviders: OAuthProviderId[];
+}
+export declare function loadNormalizedAuthUIConfig(): Promise<NormalizedAuthUIConfig>;
+export declare function normalizeAuthUIConfig(config: AuthConfigResponse): NormalizedAuthUIConfig;
+export {};

package/dist/auth-ui/default-labels.d.ts

@@ -0,0 +1,2 @@
+import { AuthUILabelOverrides, AuthUILabels } from './types';
+export declare function mergeAuthUILabels(base: AuthUILabels, overrides?: AuthUILabelOverrides): AuthUILabels;

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

@@ -0,0 +1,2 @@
+export { createAuthUIModule } from './mount';
+export type { AuthSuccessEvent, AuthUILabelOverrides, AuthUILabels, ControlledAuthUIOptions, EdgeSparkAuthUI, MountAuthUIOptions, MountedAuthUI, RedirectAuthUIOptions, } from './types';

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

@@ -0,0 +1,7 @@
+import { BetterAuthClientInstance } from '../auth/types';
+import { EdgeSparkAuthUI } from './types';
+interface ManagedAuthUIRuntimeOptions {
+    syncPublicSession?: () => Promise<void> | void;
+}
+export declare function createAuthUIModule(auth: BetterAuthClientInstance, runtimeOptions?: ManagedAuthUIRuntimeOptions): EdgeSparkAuthUI;
+export {};

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

@@ -0,0 +1,7 @@
+import { AuthSession, AuthUser, BetterAuthClientInstance } from '../auth/types';
+import { EdgeSparkAuthError } from '../errors';
+export declare function normalizeAuthError(error: unknown, fallbackMessage?: string): EdgeSparkAuthError;
+export declare function readCurrentSession(auth: BetterAuthClientInstance): Promise<{
+    user: AuthUser | null;
+    session: AuthSession | null;
+}>;