@neondatabase/auth 0.3.0-beta → 0.4.1-beta

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-import { O as VanillaBetterAuthClient, x as ReactBetterAuthClient } from "./adapter-core-B9uDhoYq.mjs";
-import { n as BetterAuthReactAdapterInstance } from "./better-auth-react-adapter-BO4jLN4H.mjs";
-import { r as SupabaseAuthAdapterInstance, s as BetterAuthVanillaAdapterInstance } from "./supabase-adapter-CSDRL1ZU.mjs";
+import { S as ReactBetterAuthClient, k as VanillaBetterAuthClient } from "./adapter-core-ClY-p_AI.mjs";
+import { n as BetterAuthReactAdapterInstance } from "./better-auth-react-adapter-iJMZCLUI.mjs";
+import { r as SupabaseAuthAdapterInstance, s as BetterAuthVanillaAdapterInstance } from "./supabase-adapter-cuLnmLDs.mjs";
+import { a as isAuthError, i as isAuthApiError, n as AuthError, t as AuthApiError } from "./auth-interface-Clz-oWq1.mjs";
 
 //#region src/neon-auth.d.ts
 
@@ -90,4 +91,4 @@ type NeonAuth<T extends NeonAuthAdapter> = {
 declare function createInternalNeonAuth<T extends NeonAuthAdapter = BetterAuthVanillaAdapterInstance>(url: string, config?: NeonAuthConfigInternal<T>): NeonAuth<T>;
 declare function createAuthClient<T extends NeonAuthAdapter = BetterAuthVanillaAdapterInstance>(url: string, config?: NeonAuthConfig<T>): NeonAuthPublicApi<T>;
 //#endregion
-export { type NeonAuth, type NeonAuthAdapter, type NeonAuthConfig, type NeonAuthPublicApi, type ReactBetterAuthClient, type VanillaBetterAuthClient, createAuthClient, createInternalNeonAuth };
+export { AuthApiError, AuthError, type NeonAuth, type NeonAuthAdapter, type NeonAuthConfig, type NeonAuthPublicApi, type ReactBetterAuthClient, type VanillaBetterAuthClient, createAuthClient, createInternalNeonAuth, isAuthApiError, isAuthError };

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import "./adapter-core-D00qcqMo.mjs";
-import { n as createInternalNeonAuth, t as createAuthClient } from "./neon-auth-DBOB8sXF.mjs";
+import "./adapter-core-BFMM3lwe.mjs";
+import { c as isAuthApiError, l as isAuthError, o as AuthApiError, s as AuthError } from "./better-auth-helpers-Bkezghej.mjs";
+import { n as createInternalNeonAuth, t as createAuthClient } from "./neon-auth-VDrC3GwX.mjs";
 
-export { createAuthClient, createInternalNeonAuth };
+export { AuthApiError, AuthError, createAuthClient, createInternalNeonAuth, isAuthApiError, isAuthError };

package/dist/{neon-auth-DBOB8sXF.mjs → neon-auth-VDrC3GwX.mjs}

@@ -1,4 +1,4 @@
-import { n as BetterAuthVanillaAdapter } from "./supabase-adapter-CIBMebXB.mjs";
+import { n as BetterAuthVanillaAdapter } from "./supabase-adapter-CAyBFrNn.mjs";
 
 //#region src/neon-auth.ts
 /**

package/dist/next/index.d.mts

@@ -1,3 +1,4 @@
+import { a as isAuthError, i as isAuthApiError, n as AuthError, t as AuthApiError } from "../auth-interface-Clz-oWq1.mjs";
 import * as better_auth_react0 from "better-auth/react";
 import * as jose0 from "jose";
 import * as better_auth_plugins0 from "better-auth/plugins";
@@ -124,15 +125,7 @@ declare function createAuthClient(): {
         id: string;
       };
       fetchOptions?: FetchOptions | undefined;
-    }>, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<{
-      id: string;
-      createdAt: Date;
-      updatedAt: Date;
-      email: string;
-      emailVerified: boolean;
-      name: string;
-      image?: string | null | undefined;
-    }, {
+    }>, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<better_auth_plugins0.UserWithRole, {
       code?: string | undefined;
       message?: string | undefined;
     }, FetchOptions["throw"] extends true ? true : false>>;
@@ -141,13 +134,13 @@ declare function createAuthClient(): {
   admin: {
     createUser: <FetchOptions extends better_auth0.ClientFetchOption<Partial<{
       email: string;
-      password: string;
+      password?: string | undefined;
       name: string;
       role?: "user" | "admin" | ("user" | "admin")[] | undefined;
       data?: Record<string, any> | undefined;
     }> & Record<string, any>, Partial<Record<string, any>> & Record<string, any>, Record<string, any> | undefined>>(data_0: better_auth0.Prettify<{
       email: string;
-      password: string;
+      password?: string | undefined;
       name: string;
       role?: "user" | "admin" | ("user" | "admin")[] | undefined;
       data?: Record<string, any> | undefined;
@@ -239,15 +232,7 @@ declare function createAuthClient(): {
     } & {
       fetchOptions?: FetchOptions | undefined;
     }>, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<{
-      user: {
-        id: string;
-        createdAt: Date;
-        updatedAt: Date;
-        email: string;
-        emailVerified: boolean;
-        name: string;
-        image?: string | null | undefined;
-      } & Record<string, any>;
+      user: better_auth_plugins0.UserWithRole;
     }, {
       code?: string | undefined;
       message?: string | undefined;
@@ -266,15 +251,7 @@ declare function createAuthClient(): {
     } & {
       fetchOptions?: FetchOptions | undefined;
     }>, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<{
-      user: {
-        id: string;
-        createdAt: Date;
-        updatedAt: Date;
-        email: string;
-        emailVerified: boolean;
-        name: string;
-        image?: string | null | undefined;
-      } & Record<string, any>;
+      user: better_auth_plugins0.UserWithRole;
     }, {
       code?: string | undefined;
       message?: string | undefined;
@@ -311,8 +288,25 @@ declare function createAuthClient(): {
       query?: Record<string, any> | undefined;
       fetchOptions?: FetchOptions | undefined;
     }> | undefined, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<{
-      session: better_auth0.Session & Record<string, any>;
-      user: better_auth0.User & Record<string, any>;
+      session: {
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        userId: string;
+        expiresAt: Date;
+        token: string;
+        ipAddress?: string | null | undefined;
+        userAgent?: string | null | undefined;
+      } & Record<string, any>;
+      user: {
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        email: string;
+        emailVerified: boolean;
+        name: string;
+        image?: string | null | undefined;
+      } & Record<string, any>;
     }, {
       code?: string | undefined;
       message?: string | undefined;
@@ -488,8 +482,6 @@ declare function createAuthClient(): {
       createdAt: Date;
       logo?: string | null | undefined | undefined;
       metadata?: any;
-    } & {
-      metadata: Record<string, any> | undefined;
     }, {
       code?: string | undefined;
       message?: string | undefined;
@@ -641,7 +633,7 @@ declare function createAuthClient(): {
       resend?: boolean | undefined;
     } & {
       fetchOptions?: FetchOptions | undefined;
-    }>, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<{
+    }>, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<NonNullable<{
       id: string;
       organizationId: string;
       email: string;
@@ -650,7 +642,16 @@ declare function createAuthClient(): {
       inviterId: string;
       expiresAt: Date;
       createdAt: Date;
-    }, {
+    } | {
+      id: string;
+      organizationId: string;
+      email: string;
+      role: "admin" | "member" | "owner";
+      status: better_auth_plugins0.InvitationStatus;
+      inviterId: string;
+      expiresAt: Date;
+      createdAt: Date;
+    }>, {
       code?: string | undefined;
       message?: string | undefined;
     }, FetchOptions["throw"] extends true ? true : false>>;
@@ -1130,25 +1131,25 @@ declare function createAuthClient(): {
       token: string;
       user: {
         id: string;
+        createdAt: Date;
+        updatedAt: Date;
         email: string;
         emailVerified: boolean;
         name: string;
-        image: string | null | undefined;
-        createdAt: Date;
-        updatedAt: Date;
-      };
+        image?: string | null | undefined;
+      } & Record<string, any>;
     } | {
       status: boolean;
       token: null;
       user: {
         id: string;
+        createdAt: Date;
+        updatedAt: Date;
         email: string;
         emailVerified: boolean;
         name: string;
-        image: string | null | undefined;
-        createdAt: Date;
-        updatedAt: Date;
-      };
+        image?: string | null | undefined;
+      } & Record<string, any>;
     }>, {
       code?: string | undefined;
       message?: string | undefined;
@@ -1168,18 +1169,33 @@ declare function createAuthClient(): {
       token: string;
       user: {
         id: string;
+        createdAt: Date;
+        updatedAt: Date;
         email: string;
         emailVerified: boolean;
         name: string;
-        image: string | null | undefined;
-        createdAt: Date;
-        updatedAt: Date;
+        image?: string | null | undefined;
       };
     }, {
       code?: string | undefined;
       message?: string | undefined;
     }, FetchOptions["throw"] extends true ? true : false>>;
   };
+} & {
+  emailOtp: {
+    requestPasswordReset: <FetchOptions extends better_auth0.ClientFetchOption<Partial<{
+      email: string;
+    }> & Record<string, any>, Partial<Record<string, any>> & Record<string, any>, Record<string, any> | undefined>>(data_0: better_auth0.Prettify<{
+      email: string;
+    } & {
+      fetchOptions?: FetchOptions | undefined;
+    }>, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<{
+      success: boolean;
+    }, {
+      code?: string | undefined;
+      message?: string | undefined;
+    }, FetchOptions["throw"] extends true ? true : false>>;
+  };
 } & {
   forgetPassword: {
     emailOtp: <FetchOptions extends better_auth0.ClientFetchOption<Partial<{
@@ -1214,6 +1230,60 @@ declare function createAuthClient(): {
       message?: string | undefined;
     }, FetchOptions["throw"] extends true ? true : false>>;
   };
+} & {
+  signIn: {
+    magicLink: <FetchOptions extends better_auth0.ClientFetchOption<Partial<{
+      email: string;
+      name?: string | undefined;
+      callbackURL?: string | undefined;
+      newUserCallbackURL?: string | undefined;
+      errorCallbackURL?: string | undefined;
+    }> & Record<string, any>, Partial<Record<string, any>> & Record<string, any>, Record<string, any> | undefined>>(data_0: better_auth0.Prettify<{
+      email: string;
+      name?: string | undefined;
+      callbackURL?: string | undefined;
+      newUserCallbackURL?: string | undefined;
+      errorCallbackURL?: string | undefined;
+    } & {
+      fetchOptions?: FetchOptions | undefined;
+    }>, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<{
+      status: boolean;
+    }, {
+      code?: string | undefined;
+      message?: string | undefined;
+    }, FetchOptions["throw"] extends true ? true : false>>;
+  };
+} & {
+  magicLink: {
+    verify: <FetchOptions extends better_auth0.ClientFetchOption<never, Partial<{
+      token: string;
+      callbackURL?: string | undefined;
+      errorCallbackURL?: string | undefined;
+      newUserCallbackURL?: string | undefined;
+    }> & Record<string, any>, Record<string, any> | undefined>>(data_0: better_auth0.Prettify<{
+      query: {
+        token: string;
+        callbackURL?: string | undefined;
+        errorCallbackURL?: string | undefined;
+        newUserCallbackURL?: string | undefined;
+      };
+      fetchOptions?: FetchOptions | undefined;
+    }>, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<{
+      token: string;
+      user: {
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        email: string;
+        emailVerified: boolean;
+        name: string;
+        image?: string | null | undefined;
+      };
+    }, {
+      code?: string | undefined;
+      message?: string | undefined;
+    }, FetchOptions["throw"] extends true ? true : false>>;
+  };
 } & {
   signIn: {
     social: <FetchOptions extends better_auth0.ClientFetchOption<Partial<{
@@ -1436,13 +1506,13 @@ declare function createAuthClient(): {
     token: string | null;
     user: {
       id: string;
-      email: string;
-      name: string;
-      image: string | null | undefined;
-      emailVerified: boolean;
       createdAt: Date;
       updatedAt: Date;
-    };
+      email: string;
+      emailVerified: boolean;
+      name: string;
+      image?: string | null | undefined;
+    } & Record<string, any>;
   }, {
     code?: string | undefined;
     message?: string | undefined;
@@ -1606,13 +1676,13 @@ declare function createAuthClient(): {
     query?: Record<string, any> | undefined;
     fetchOptions?: FetchOptions | undefined;
   }> | undefined, data_1?: FetchOptions | undefined) => Promise<_better_fetch_fetch0.BetterFetchResponse<{
+    scopes: string[];
     id: string;
-    providerId: string;
     createdAt: Date;
     updatedAt: Date;
-    accountId: string;
     userId: string;
-    scopes: string[];
+    providerId: string;
+    accountId: string;
   }[], {
     code?: string | undefined;
     message?: string | undefined;
@@ -1975,6 +2045,7 @@ declare function createAuthClient(): {
     })[];
     cache?: RequestCache | undefined;
     method: string;
+    window?: null | undefined;
     headers?: (HeadersInit & (HeadersInit | {
       accept: "application/json" | "text/plain" | "application/octet-stream";
       "content-type": "application/json" | "text/plain" | "application/x-www-form-urlencoded" | "multipart/form-data" | "application/octet-stream";
@@ -1989,7 +2060,6 @@ declare function createAuthClient(): {
     referrer?: string | undefined;
     referrerPolicy?: ReferrerPolicy | undefined;
     signal?: (AbortSignal | null) | undefined;
-    window?: null | undefined;
     onRetry?: ((response: _better_fetch_fetch0.ResponseContext) => Promise<void> | void) | undefined;
     hookOptions?: {
       cloneResponse?: boolean;
@@ -2130,7 +2200,25 @@ declare function createAuthClient(): {
     readonly FAILED_TO_UNLINK_LAST_ACCOUNT: "You can't unlink your last account";
     readonly ACCOUNT_NOT_FOUND: "Account not found";
     readonly USER_ALREADY_HAS_PASSWORD: "User already has a password. Provide that to delete the account.";
+    readonly CROSS_SITE_NAVIGATION_LOGIN_BLOCKED: "Cross-site navigation login blocked. This request appears to be a CSRF attack.";
+    readonly VERIFICATION_EMAIL_NOT_ENABLED: "Verification email isn't enabled";
+    readonly EMAIL_ALREADY_VERIFIED: "Email is already verified";
+    readonly EMAIL_MISMATCH: "Email mismatch";
+    readonly SESSION_NOT_FRESH: "Session is not fresh";
+    readonly LINKED_ACCOUNT_ALREADY_EXISTS: "Linked account already exists";
+    readonly INVALID_ORIGIN: "Invalid origin";
+    readonly INVALID_CALLBACK_URL: "Invalid callbackURL";
+    readonly INVALID_REDIRECT_URL: "Invalid redirectURL";
+    readonly INVALID_ERROR_CALLBACK_URL: "Invalid errorCallbackURL";
+    readonly INVALID_NEW_USER_CALLBACK_URL: "Invalid newUserCallbackURL";
+    readonly MISSING_OR_NULL_ORIGIN: "Missing or null Origin";
+    readonly CALLBACK_URL_REQUIRED: "callbackURL is required";
+    readonly FAILED_TO_CREATE_VERIFICATION: "Unable to create verification";
+    readonly FIELD_NOT_ALLOWED: "Field not allowed to be set";
+    readonly ASYNC_VALIDATION_NOT_SUPPORTED: "Async validation is not supported";
+    readonly VALIDATION_ERROR: "Validation Error";
+    readonly MISSING_FIELD: "Field is required";
   };
 };
 //#endregion
-export { createAuthClient };
+export { AuthApiError, AuthError, createAuthClient, isAuthApiError, isAuthError };

package/dist/next/index.mjs

@@ -1,6 +1,7 @@
-import "../adapter-core-D00qcqMo.mjs";
-import { t as BetterAuthReactAdapter } from "../better-auth-react-adapter-Xdj-69i9.mjs";
-import { t as createAuthClient$1 } from "../neon-auth-DBOB8sXF.mjs";
+import "../adapter-core-BFMM3lwe.mjs";
+import { c as isAuthApiError, l as isAuthError, o as AuthApiError, s as AuthError } from "../better-auth-helpers-Bkezghej.mjs";
+import { t as BetterAuthReactAdapter } from "../better-auth-react-adapter-DZTZVVnk.mjs";
+import { t as createAuthClient$1 } from "../neon-auth-VDrC3GwX.mjs";
 
 //#region src/next/index.ts
 function createAuthClient() {
@@ -8,4 +9,4 @@ function createAuthClient() {
 }
 
 //#endregion
-export { createAuthClient };
+export { AuthApiError, AuthError, createAuthClient, isAuthApiError, isAuthError };

package/dist/next/server/index.d.mts

@@ -1,11 +1,51 @@
-import { O as VanillaBetterAuthClient } from "../../adapter-core-B9uDhoYq.mjs";
+import { k as VanillaBetterAuthClient } from "../../adapter-core-ClY-p_AI.mjs";
+import { a as isAuthError, i as isAuthApiError, n as AuthError, t as AuthApiError } from "../../auth-interface-Clz-oWq1.mjs";
 import { NextRequest, NextResponse } from "next/server";
 
-//#region src/server/config.d.ts
-
+//#region src/server/logger.d.ts
 /**
- * Framework-agnostic configuration types for Neon Auth
+ * Framework-agnostic logging for Neon Auth server-side proxy and middleware.
  */
+/** Supported Neon Auth log levels (`'silent'` disables all Neon Auth SDK `console` output). */
+type NeonAuthLogLevel = 'error' | 'warn' | 'info' | 'debug' | 'silent';
+/**
+ * Optional injectable logger. Omitted methods fall back to `console`.
+ *
+ * Custom implementations may receive structured fields such as `err` (the raw caught value)
+ * alongside `detail` for richer sinks (Sentry, OTel).
+ */
+type NeonAuthLogger = Partial<{
+  error(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  debug(message: string, meta?: Record<string, unknown>): void;
+}>;
+/** Resolved sink after merging defaults and level filtering (same shape as {@link NeonAuthLogger} with all methods required). */
+type ResolvedNeonAuthLogging = Required<NeonAuthLogger>;
+/**
+ * Logger / level options for Neon Auth server surfaces.
+ *
+ * When **`logLevel`** is **`'silent'`**, any **`logger`** is ignored at runtime (full mute).
+ */
+type NeonAuthLoggingInput = {
+  logger?: NeonAuthLogger;
+  /**
+   * Minimum level for Neon Auth logs. **`'silent'`** disables all Neon Auth `console` output.
+   * @default 'warn' — emits `error` and `warn` only
+   */
+  logLevel?: NeonAuthLogLevel;
+};
+/**
+ * Merges user logger with `console`, applies {@link NeonAuthLoggingInput} level rules.
+ *
+ * **Opt-out:** Defaults to `warn` (structured `error` / `warn` to `console`). Set **`logLevel: 'silent'`**
+ * to disable completely. Custom **`logger`** overrides `console` per level when not silent.
+ */
+declare function resolveNeonAuthLogging(input?: NeonAuthLoggingInput): ResolvedNeonAuthLogging;
+//#endregion
+//#region src/server/config.d.ts
+/** Allowed values for the `SameSite` attribute on Neon Auth cookies. */
+type SessionCookieSameSite = 'strict' | 'lax' | 'none';
 /**
  * Session cookie configuration
  */
@@ -41,11 +81,18 @@ interface SessionCookieConfig {
    * @example '.example.com' // Share across subdomains
    */
   domain?: string;
+  /**
+   * `SameSite` for cookies set or rewritten by the server proxy (API route, middleware, RSC).
+   *
+   * - **`strict` (default)** — cookies are not sent on cross-site requests (strongest default).
+   * - **`lax`** — previous hard-coded behavior; cookies sent on top-level cross-site navigations.
+   * - **`none`** — use for third-party contexts (for example your app embedded in another site’s iframe); requires `Secure` (always applied for these cookies).
+   *
+   * @default 'strict'
+   */
+  sameSite?: SessionCookieSameSite;
 }
-/**
- * Base configuration for Neon Auth server utilities
- */
-interface NeonAuthConfig {
+type NeonAuthBase = {
   /**
    * Base URL for the Neon Auth server
    * @example 'https://ep-xxxx.neonauth.us-east-1.aws.neon.tech'
@@ -55,18 +102,27 @@ interface NeonAuthConfig {
    * Cookie configuration
    */
   cookies: SessionCookieConfig;
-}
+};
 /**
- * Configuration for Neon Auth middleware
- * Extends base config with middleware-specific options
+ * Base configuration for Neon Auth server utilities.
+ *
+ * Combines connection settings with {@link NeonAuthLoggingInput} (`logger`, `logLevel`, including `'silent'`).
  */
-interface NeonAuthMiddlewareConfig extends NeonAuthConfig {
+type NeonAuthConfig = NeonAuthBase & NeonAuthLoggingInput;
+/**
+ * Configuration for Neon Auth middleware.
+ */
+type NeonAuthMiddlewareConfig = NeonAuthConfig & {
   /**
    * URL to redirect to when user is not authenticated
    * @default '/auth/sign-in'
    */
   loginUrl?: string;
-}
+  /**
+   * Pre-resolved sink from {@link resolveNeonAuthLogging}. Set by {@link createNeonAuth} so middleware shares the same logging configuration as the API handler without resolving per request.
+   */
+  log?: ResolvedNeonAuthLogging;
+};
 //#endregion
 //#region src/next/server/handler.d.ts
 type Params = {
@@ -136,6 +192,9 @@ declare function authApiHandler(config: NeonAuthConfig): {
  * @param config.cookies - Cookie configuration
  * @param config.cookies.secret - Secret for signing session cookies (minimum 32 characters)
  * @param config.cookies.sessionDataTtl - Optional TTL for session cache in seconds (default: 300)
+ * @param config.logger - Optional structured logger; omitted methods fall back to `console`
+ * @param config.logLevel - Minimum log level; `'silent'` disables Neon Auth console output (default: `warn`)
+ * @param config.log - Pre-resolved logging sink (set by {@link createNeonAuth})
  * @param config.loginUrl - The URL to redirect to when the user is not authenticated (default: '/auth/sign-in')
  * @returns A middleware function that can be used in the Next.js app.
  * @throws Error if `cookies.secret` is less than 32 characters
@@ -198,6 +257,10 @@ declare const API_ENDPOINTS: {
       readonly path: "sign-in/email-otp";
       readonly method: "POST";
     };
+    readonly magicLink: {
+      readonly path: "sign-in/magic-link";
+      readonly method: "POST";
+    };
   };
   readonly signUp: {
     readonly email: {
@@ -419,9 +482,61 @@ declare const API_ENDPOINTS: {
       readonly method: "POST";
     };
   };
+  readonly magicLink: {
+    readonly verify: {
+      readonly path: "magic-link/verify";
+      readonly method: "GET";
+    };
+  };
+};
+//#endregion
+//#region src/server/network-error.d.ts
+/**
+ * Classifies failed upstream `fetch` calls for clearer client responses and logs.
+ */
+/**
+ * Semver-stable transport error codes surfaced as JSON `code` on synthetic HTTP responses
+ * (for example 502 from the proxy) and in logs. Treat adding values as non-breaking;
+ * renaming or removing values is a breaking change.
+ */
+declare const NEON_AUTH_NETWORK_ERROR_CODES: readonly ["NETWORK_ERROR", "NETWORK_DNS", "NETWORK_REFUSED", "NETWORK_TIMEOUT", "NETWORK_TLS", "NETWORK_RESET", "NETWORK_ABORT"];
+/** @see NEON_AUTH_NETWORK_ERROR_CODES */
+type NeonAuthNetworkErrorCode = (typeof NEON_AUTH_NETWORK_ERROR_CODES)[number];
+/**
+ * Result of {@link classifyFetchFailure}: a transport failure with a stable
+ * {@link NeonAuthNetworkErrorCode}, or an internal/unclassified error (detail for logs only).
+ */
+type ClassifiedFetchFailure = {
+  kind: 'transport';
+  code: NeonAuthNetworkErrorCode;
+  /** Safe short detail for logs (no secrets) */
+  detail?: string;
+  /** Safe message for JSON bodies returned to clients */
+  clientMessage: string;
+} | {
+  kind: 'internal';
+  /** Truncated detail for server-side logs only */
+  detail?: string;
+  /** Generic message for JSON bodies — never echo raw `Error.message` */
+  clientMessage: string;
 };
+/**
+ * Inspects an error from `fetch` (including `cause` and aggregate errors) and
+ * returns a stable code for responses and observability.
+ */
+declare function classifyFetchFailure(error: unknown): ClassifiedFetchFailure;
 //#endregion
 //#region src/server/types.d.ts
+/**
+ * Error shape returned from Neon Auth server API helpers (`auth.signIn`, `getSession`, etc.)
+ * when the upstream call fails. `code` is a transport code, `'INTERNAL_ERROR'`, or a Better Auth HTTP error code string.
+ */
+type NeonAuthServerApiError = {
+  message: string;
+  status: number;
+  statusText: string;
+  code: NeonAuthNetworkErrorCode | 'INTERNAL_ERROR' | (string & {});
+};
 /**
  * Extract top-level keys from API_ENDPOINTS.
  * For nested endpoints like signIn.email, this extracts 'signIn' (not 'email').
@@ -454,6 +569,8 @@ type NeonAuthServer = Pick<VanillaBetterAuthClient, ServerAuthMethods>;
  * @param config.cookies.secret - Secret for signing session cookies (minimum 32 characters)
  * @param config.cookies.sessionDataTtl - Optional TTL for session cache in seconds (default: 300)
  * @param config.cookies.domain - Optional cookie domain (default: current domain)
+ * @param config.logger - Optional structured logger; omitted methods fall back to `console` (see {@link NeonAuthLogger})
+ * @param config.logLevel - Minimum level; `'silent'` disables Neon Auth server console logs (default: `warn`)
  * @returns Unified auth instance with server methods, handler, and middleware
  * @throws Error if `cookies.secret` is less than 32 characters
  *
@@ -533,4 +650,4 @@ type NeonAuth = NeonAuthServer & {
   middleware: (middlewareConfig?: Pick<NeonAuthMiddlewareConfig, 'loginUrl'>) => ReturnType<typeof neonAuthMiddleware>;
 };
 //#endregion
-export { NeonAuth, createNeonAuth };
+export { AuthApiError, AuthError, type ClassifiedFetchFailure, NEON_AUTH_NETWORK_ERROR_CODES, NeonAuth, type NeonAuthLogLevel, type NeonAuthLogger, type NeonAuthLoggingInput, type NeonAuthNetworkErrorCode, type NeonAuthServerApiError, type ResolvedNeonAuthLogging, classifyFetchFailure, createNeonAuth, isAuthApiError, isAuthError, resolveNeonAuthLogging };