@edgespark/web 0.0.0-beta.920378e

package/README.md

@@ -0,0 +1,281 @@
+# `@edgespark/web`
+
+EdgeSpark browser SDK.
+
+This package is intentionally:
+
+- browser-only
+- same-origin only
+- cookie-session only
+- zero-config
+- optimized for agent-written code
+
+Recommended browser auth path:
+
+- use `@edgespark/web` for all browser auth
+- prefer `authUI.mount()` for managed auth UI
+- use `es.auth` for custom flows
+- do not implement app auth by calling `/api/_es/auth/*` manually
+
+## 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",
+});
+```
+
+Auto-detected labels are used by default. The managed UI picks the best preset
+from the browser's language preferences automatically.
+
+## 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` keeps better-auth's API shape and adds two EdgeSpark helpers:
+
+```ts
+const session = await es.auth.requireSession();
+
+const unsubscribe = es.auth.onSessionChange((nextSession) => {
+  console.log(nextSession?.user.email ?? "signed out");
+});
+```
+
+`requireSession()` throws `UNAUTHENTICATED` only when no session exists. If the
+session lookup itself fails, it preserves the upstream auth error code/status
+so route guards can distinguish backend failures from a real sign-out.
+
+`onSessionChange()` is hydration-safe: it waits for the first session lookup to
+complete before emitting, so apps do not mistake initial loading for a real
+signed-out state. Successful sign-in/sign-up/sign-out mutations also prompt
+other tabs to refetch their session state.
+
+Current platform note:
+- `changeEmail()`
+- `deleteUser()`
+- `deleteUserCallback()`
+
+still appear on the familiar better-auth-shaped surface, but EdgeSpark does
+not currently enable those platform capabilities. These methods fail fast with
+`UNSUPPORTED_AUTH_METHOD`. For normal browser auth flows, stay on the supported
+paths: `authUI.mount()` for managed UI and `es.auth` for supported custom flows.
+
+Use the familiar 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();
+```
+
+The platform-managed `/api/_es/auth/*` routes exist underneath the SDK, but normal app code should not call them directly. Treat those routes as implementation details unless you are debugging auth at the HTTP layer.
+
+### `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.
+
+`onError` always receives a normalized `EdgeSparkAuthError`, so callback code
+can safely read `error.code`, `error.message`, and `error.status` without
+defensive `unknown` handling.
+
+```ts
+es.authUI.mount(container, {
+  onSuccess(event) {
+    if (event.action !== "password-reset") {
+      window.location.assign("/dashboard");
+    }
+  },
+  onError(error) {
+    console.error(error.code, error.message);
+  },
+});
+```
+
+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
+- if the platform keeps JWT session cookie cache enabled, reset-time session revocation remains eventually consistent for already-open browser contexts and may take up to the cache TTL to become visible
+
+In controlled mode, `authUI` stops mutating the container after `onSuccess`
+runs. If the app wants to close, replace, or reuse that container, it owns that
+teardown explicitly.
+
+#### Appearance
+
+Managed auth supports a small, explicit appearance contract. If `appearance` is
+omitted, the UI keeps its built-in default styling.
+
+- `theme` selects the built-in starting preset
+- `variables` override specific design tokens on top of that preset
+- `className` adds a stable root hook for app-scoped CSS
+
+```ts
+import {
+  AUTH_UI_APPEARANCE_VARIABLE,
+  AUTH_UI_THEME,
+  type AuthUIAppearance,
+} from "@edgespark/web";
+
+const appearance = {
+  theme: AUTH_UI_THEME.DARK,
+  className: "my-auth-surface",
+  variables: {
+    [AUTH_UI_APPEARANCE_VARIABLE.PRIMARY]: "#d97d4a",
+    [AUTH_UI_APPEARANCE_VARIABLE.FONT]: '"Manrope", sans-serif',
+  },
+} satisfies AuthUIAppearance;
+
+es.authUI.mount(container, {
+  redirectTo: "/dashboard",
+  appearance,
+});
+```
+
+Supported appearance fields:
+
+- `theme`: `"light"` or `"dark"` (`"light"` is the default)
+- `className`: applied to the managed auth UI root container
+- `variables`: stable CSS custom properties for light-touch theming
+
+`appearance.variables` are applied as inline CSS custom properties on the
+managed auth root, so explicit overrides win over the built-in stylesheet
+defaults without requiring consumers to manage CSS load order.
+
+When the appearance object is assigned to a variable before calling
+`authUI.mount(...)`, prefer `satisfies AuthUIAppearance` so `tsc` rejects
+unsupported theme values, unsupported token keys, and misspelled appearance
+fields during type-checking.
+
+Supported `appearance.variables` keys:
+
+| Variable | Controls | Light default |
+|----------|----------|---------------|
+| `--edgespark-auth-bg` | Page/input background, status mix base | `#ffffff` |
+| `--edgespark-auth-bg-muted` | Secondary button hover, muted status bg, modal close hover | `#f7f7f8` |
+| `--edgespark-auth-card-bg` | Card background (accepts gradient or flat color) | `linear-gradient(180deg, #ffffff, #fcfcfc)` |
+| `--edgespark-auth-border` | Input border, secondary button border, divider line | `rgba(15,23,42,0.08)` |
+| `--edgespark-auth-text` | All body text | `#111827` |
+| `--edgespark-auth-text-muted` | Subtitles, meta text, divider label, modal close icon | `#6b7280` |
+| `--edgespark-auth-divider-bg` | Divider pill background (masks the line behind the label) | inherits `--edgespark-auth-bg` |
+| `--edgespark-auth-primary` | Primary button bg, links, input focus ring + border | `#0f766e` |
+| `--edgespark-auth-primary-hover` | Primary button hover bg | `#115e59` |
+| `--edgespark-auth-primary-contrast` | Primary button text | `#ffffff` |
+| `--edgespark-auth-error` | Error status text + tinted bg | `#b91c1c` |
+| `--edgespark-auth-info` | Info status text + tinted bg | `#0f766e` |
+| `--edgespark-auth-radius-card` | Card border radius | `20px` |
+| `--edgespark-auth-radius-control` | Input border radius | `12px` |
+| `--edgespark-auth-shadow` | Card box shadow | `0 24px 60px rgba(15,23,42,0.08)` |
+| `--edgespark-auth-font` | Root font family | `"IBM Plex Sans", "Inter", ui-sans-serif, system-ui, sans-serif` |
+| `--edgespark-auth-modal-backdrop` | OAuth modal overlay background | `rgba(15,23,42,0.22)` |
+| `--edgespark-auth-modal-card-bg` | OAuth modal card background | `#ffffff` |
+| `--edgespark-auth-modal-shadow` | OAuth modal card box shadow | `0 24px 60px rgba(15,23,42,0.18)` |
+
+Only the root container hook, the theme attribute, and the documented CSS
+variables above are part of the managed auth appearance contract. Internal
+`.edgespark-auth__*` classes remain implementation details and should not be
+treated as a stable public API.
+
+## 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.
+
+## Locale presets
+
+Managed auth UI labels auto-detect by default, so most apps do not need to
+import locale helpers manually.
+
+Import a preset only when the app wants to force a specific language or build
+on top of a known base:
+
+```ts
+import { createEdgeSpark, fr } from "@edgespark/web";
+
+const es = createEdgeSpark();
+
+es.authUI.mount(container, {
+  redirectTo: "/dashboard",
+  labels: fr,
+});
+```
+
+`detectLocale()` is exported for advanced cases that want the same browser
+language matching outside the managed auth UI.
+
+## 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,270 @@
+[data-edgespark-auth] {
+  --edgespark-auth-bg: #ffffff;
+  --edgespark-auth-bg-muted: #f7f7f8;
+  --edgespark-auth-card-bg: linear-gradient(180deg, #ffffff 0%, #fcfcfc 100%);
+  --edgespark-auth-border: rgba(15, 23, 42, 0.08);
+  --edgespark-auth-text: #111827;
+  --edgespark-auth-text-muted: #6b7280;
+  --edgespark-auth-divider-bg: var(--edgespark-auth-bg);
+  --edgespark-auth-primary: #0f766e;
+  --edgespark-auth-primary-hover: #115e59;
+  --edgespark-auth-primary-contrast: #ffffff;
+  --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;
+  --edgespark-auth-modal-backdrop: rgba(15, 23, 42, 0.22);
+  --edgespark-auth-modal-card-bg: #ffffff;
+  --edgespark-auth-modal-shadow: 0 24px 60px rgba(15, 23, 42, 0.18);
+  color: var(--edgespark-auth-text);
+  font-family: var(--edgespark-auth-font);
+}
+
+[data-edgespark-auth][data-edgespark-auth-theme="dark"] {
+  --edgespark-auth-bg: #14181f;
+  --edgespark-auth-bg-muted: #1d2330;
+  --edgespark-auth-card-bg: linear-gradient(180deg, #171d27 0%, #121823 100%);
+  --edgespark-auth-border: rgba(226, 232, 240, 0.12);
+  --edgespark-auth-text: #f8fafc;
+  --edgespark-auth-text-muted: #94a3b8;
+  --edgespark-auth-divider-bg: var(--edgespark-auth-bg);
+  --edgespark-auth-primary: #14b8a6;
+  --edgespark-auth-primary-hover: #0f9488;
+  --edgespark-auth-primary-contrast: #f8fafc;
+  --edgespark-auth-error: #fca5a5;
+  --edgespark-auth-info: #5eead4;
+  --edgespark-auth-shadow: 0 24px 60px rgba(2, 6, 23, 0.32);
+  --edgespark-auth-modal-backdrop: rgba(2, 6, 23, 0.56);
+  --edgespark-auth-modal-card-bg: #101722;
+  --edgespark-auth-modal-shadow: 0 24px 60px rgba(2, 6, 23, 0.48);
+}
+
+[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: var(--edgespark-auth-card-bg);
+  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: var(--edgespark-auth-primary-contrast);
+}
+
+.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-divider-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%, var(--edgespark-auth-bg));
+}
+
+.edgespark-auth__status--info {
+  color: var(--edgespark-auth-info);
+  background: color-mix(in srgb, var(--edgespark-auth-info) 10%, var(--edgespark-auth-bg));
+}
+
+.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: var(--edgespark-auth-modal-backdrop);
+}
+
+.edgespark-auth__iframe-modal-card {
+  position: relative;
+  display: grid;
+  gap: 16px;
+  width: min(520px, 100%);
+  padding: 28px;
+  border-radius: 24px;
+  background: var(--edgespark-auth-modal-card-bg);
+  box-shadow: var(--edgespark-auth-modal-shadow);
+}
+
+.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,18 @@
+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.
+ *
+ * The exposed API intentionally keeps better-auth's shape so existing upstream
+ * knowledge transfers directly. EdgeSpark adds session helpers and sync
+ * semantics on top of that familiar 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,84 @@
+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 the auth API shape aligned with better-auth while adding a
+ * small set of session helpers on top.
+ *
+ * Most upstream auth methods remain available on the familiar better-auth
+ * shape. Some upstream methods may still be intentionally unsupported by the
+ * current EdgeSpark platform capability set even though they exist on the
+ * underlying better-auth client surface. In those cases, the facade throws an
+ * `EdgeSparkAuthError` with code `UNSUPPORTED_AUTH_METHOD` instead of deferring
+ * to a platform-specific 400/404 response.
+ */
+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.
+     *
+     * If the session lookup itself fails (offline, 5xx, etc.), this throws an
+     * `EdgeSparkAuthError` that preserves the upstream error code/status instead
+     * of collapsing the failure into `UNAUTHENTICATED`.
+     */
+    requireSession(): Promise<AuthSession>;
+    /**
+     * Subscribes to session changes for the current browser context.
+     *
+     * The first emission is hydration-safe: it waits for the initial server
+     * session lookup to complete before firing, so subscribers never receive a
+     * premature `null` while a cookie session is still settling.
+     *
+     * After hydration, successful session atom updates are forwarded immediately.
+     * Successful auth mutations that create or clear a session in the current
+     * tab also prompt other tabs to refetch their session state, so logout and
+     * same-tab sign-in/sign-up converge quickly across tabs.
+     *
+     * Transient lookup failures that temporarily clear the atom to `null` are
+     * ignored so subscribers do not mistake a backend error for a real sign-out.
+     *
+     * Returns an unsubscribe function.
+     */
+    onSessionChange(callback: SessionChangeCallback): () => void;
+    /**
+     * Signs out and then best-effort synchronizes session state for the current
+     * tab and other open tabs.
+     *
+     * The underlying better-auth result is returned unchanged.
+     */
+    signOut(...args: Parameters<BetterAuthClientInstance["signOut"]>): ReturnType<BetterAuthClientInstance["signOut"]>;
+    /**
+     * Currently unsupported by EdgeSpark platform auth.
+     *
+     * The method remains present to preserve the familiar better-auth API shape,
+     * but the facade throws `UNSUPPORTED_AUTH_METHOD` until the platform enables
+     * this capability. For browser auth, prefer supported `client.auth` methods
+     * or `authUI.mount()` instead of dropping to raw `/api/_es/auth/*` routes.
+     */
+    changeEmail(...args: Parameters<BetterAuthClientInstance["changeEmail"]>): ReturnType<BetterAuthClientInstance["changeEmail"]>;
+    /**
+     * Currently unsupported by EdgeSpark platform auth.
+     *
+     * The method remains present to preserve the familiar better-auth API shape,
+     * but the facade throws `UNSUPPORTED_AUTH_METHOD` until the platform enables
+     * this capability. Handle account removal through your own app flow until the
+     * platform adds first-class support.
+     */
+    deleteUser(...args: Parameters<BetterAuthClientInstance["deleteUser"]>): ReturnType<BetterAuthClientInstance["deleteUser"]>;
+};