@lenne.tech/nuxt-extensions 1.0.1 → 1.1.0

package/dist/module.d.mts

@@ -2,7 +2,8 @@ import * as _nuxt_schema from '@nuxt/schema';
 import { LtExtensionsModuleOptions } from '../dist/runtime/types/index.js';
 export { LtAuthClientConfig, LtAuthMode, LtAuthResponse, LtAuthState, LtPasskeyAuthResult, LtPasskeyRegisterResult, LtUser, UseLtAuthReturn } from '../dist/runtime/types/auth.js';
 export { LtFileInfo, LtUploadItem, LtUploadOptions, LtUploadProgress, LtUploadStatus, UseLtFileReturn, UseLtTusUploadReturn } from '../dist/runtime/types/upload.js';
-export { LtAuthModuleOptions, LtExtensionsModuleOptions, LtExtensionsPublicRuntimeConfig, LtI18nModuleOptions, LtTusModuleOptions } from '../dist/runtime/types/module.js';
+export { LtAuthModuleOptions, LtErrorTranslationModuleOptions, LtExtensionsModuleOptions, LtExtensionsPublicRuntimeConfig, LtI18nModuleOptions, LtTusModuleOptions } from '../dist/runtime/types/module.js';
+export { LtErrorTranslationResponse, LtParsedError, UseLtErrorTranslationReturn } from '../dist/runtime/types/error.js';
 
 declare const name = "@lenne.tech/nuxt-extensions";
 declare const version = "1.0.0";

package/dist/module.mjs

@@ -18,6 +18,10 @@ const defaultOptions = {
     loginPath: "/auth/login",
     twoFactorRedirectPath: "/auth/2fa"
   },
+  errorTranslation: {
+    enabled: true,
+    defaultLocale: "de"
+  },
   i18n: {
     autoMerge: true
   },
@@ -38,6 +42,7 @@ const module$1 = defineNuxtModule({
     const { resolve } = createResolver(import.meta.url);
     const resolvedOptions = {
       auth: { ...defaultOptions.auth, ...options.auth },
+      errorTranslation: { ...defaultOptions.errorTranslation, ...options.errorTranslation },
       i18n: { ...defaultOptions.i18n, ...options.i18n },
       tus: { ...defaultOptions.tus, ...options.tus }
     };
@@ -56,6 +61,10 @@ const module$1 = defineNuxtModule({
         loginPath: resolvedOptions.auth?.loginPath || "/auth/login",
         twoFactorRedirectPath: resolvedOptions.auth?.twoFactorRedirectPath || "/auth/2fa"
       },
+      errorTranslation: {
+        enabled: resolvedOptions.errorTranslation?.enabled ?? true,
+        defaultLocale: resolvedOptions.errorTranslation?.defaultLocale || "de"
+      },
       tus: {
         defaultChunkSize: resolvedOptions.tus?.defaultChunkSize || 5 * 1024 * 1024,
         defaultEndpoint: resolvedOptions.tus?.defaultEndpoint || "/files/upload"
@@ -66,6 +75,10 @@ const module$1 = defineNuxtModule({
       { name: "useLtAuth", from: resolve("./runtime/composables/auth/use-lt-auth") },
       { name: "useLtAuthClient", from: resolve("./runtime/composables/use-lt-auth-client") },
       { name: "ltAuthClient", from: resolve("./runtime/composables/use-lt-auth-client") },
+      {
+        name: "useLtErrorTranslation",
+        from: resolve("./runtime/composables/use-lt-error-translation")
+      },
       { name: "useLtFile", from: resolve("./runtime/composables/use-lt-file") },
       { name: "useLtTusUpload", from: resolve("./runtime/composables/use-lt-tus-upload") },
       { name: "useLtShare", from: resolve("./runtime/composables/use-lt-share") },
@@ -102,6 +115,9 @@ const module$1 = defineNuxtModule({
     if (resolvedOptions.auth?.enabled && resolvedOptions.auth?.interceptor?.enabled) {
       addPlugin(resolve("./runtime/plugins/auth-interceptor.client"));
     }
+    if (resolvedOptions.errorTranslation?.enabled) {
+      addPlugin(resolve("./runtime/plugins/error-translation.client"));
+    }
     if (resolvedOptions.i18n?.autoMerge) {
       nuxt.hook(
         "i18n:registerModule",

package/dist/runtime/composables/index.d.ts

@@ -3,3 +3,4 @@ export { useLtAuthClient, ltAuthClient } from "./use-lt-auth-client.js";
 export { useLtTusUpload } from "./use-lt-tus-upload.js";
 export { useLtFile } from "./use-lt-file.js";
 export { useLtShare, type UseLtShareReturn } from "./use-lt-share.js";
+export { useLtErrorTranslation } from "./use-lt-error-translation.js";

package/dist/runtime/composables/index.js

@@ -3,3 +3,4 @@ export { useLtAuthClient, ltAuthClient } from "./use-lt-auth-client.js";
 export { useLtTusUpload } from "./use-lt-tus-upload.js";
 export { useLtFile } from "./use-lt-file.js";
 export { useLtShare } from "./use-lt-share.js";
+export { useLtErrorTranslation } from "./use-lt-error-translation.js";

package/dist/runtime/composables/use-lt-auth-client.d.ts

@@ -17,11 +17,19 @@
  * ```
  */
 import { type LtAuthClient } from "../lib/auth-client.js";
+/**
+ * Reset the auth client singleton (useful for testing or config changes)
+ */
+export declare function resetLtAuthClient(): void;
 /**
  * Returns the Better-Auth client singleton
  *
  * The client is created once and reused across all calls.
  * Configuration is read from RuntimeConfig on first call.
+ *
+ * IMPORTANT: In dev mode, the basePath is automatically prefixed with '/api'
+ * to leverage Nuxt's server proxy. This is required for WebAuthn/Passkey
+ * to work correctly (same-origin policy).
  */
 export declare function useLtAuthClient(): LtAuthClient;
 export declare const ltAuthClient: {

package/dist/runtime/composables/use-lt-auth-client.js

@@ -1,14 +1,38 @@
 import { useNuxtApp } from "#imports";
 import { createLtAuthClient } from "../lib/auth-client.js";
 let authClientInstance = null;
+export function resetLtAuthClient() {
+  authClientInstance = null;
+}
+function isDevMode() {
+  if (import.meta.server) {
+    return process.env.NODE_ENV !== "production";
+  }
+  if (typeof window !== "undefined") {
+    const buildId = window.__NUXT__?.config?.app?.buildId;
+    if (buildId === "dev") {
+      return true;
+    }
+    const hostname = window.location?.hostname;
+    if (hostname === "localhost" || hostname === "127.0.0.1") {
+      return true;
+    }
+  }
+  return false;
+}
 export function useLtAuthClient() {
   if (!authClientInstance) {
     try {
       const nuxtApp = useNuxtApp();
       const config = nuxtApp.$config?.public?.ltExtensions?.auth || {};
+      const isDev = isDevMode();
+      let basePath = config.basePath || "/iam";
+      if (isDev && basePath && !basePath.startsWith("/api")) {
+        basePath = `/api${basePath}`;
+      }
       authClientInstance = createLtAuthClient({
-        baseURL: config.baseURL,
-        basePath: config.basePath,
+        baseURL: isDev ? "" : config.baseURL,
+        basePath,
         twoFactorRedirectPath: config.twoFactorRedirectPath,
         enableAdmin: config.enableAdmin,
         enableTwoFactor: config.enableTwoFactor,

package/dist/runtime/composables/use-lt-error-translation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Error Translation Composable
+ *
+ * Translates backend error codes to user-friendly messages.
+ * Works with or without @nuxtjs/i18n.
+ *
+ * Backend error format: "#LTNS_0100: Unauthorized - User is not logged in"
+ * Translations loaded from: GET /api/i18n/errors/:locale
+ */
+import type { UseLtErrorTranslationReturn } from "../types/error.js";
+/**
+ * Error Translation composable
+ *
+ * @returns Functions and state for error translation
+ *
+ * @example
+ * ```typescript
+ * const { translateError, showErrorToast, parseError } = useLtErrorTranslation();
+ *
+ * // Translate error from API response
+ * const message = translateError(error.message);
+ * // Input: "#LTNS_0100: Unauthorized - User is not logged in"
+ * // Output: "Sie sind nicht angemeldet." (when locale is 'de')
+ *
+ * // Show error as toast
+ * showErrorToast(error, 'Login fehlgeschlagen');
+ *
+ * // Parse error for custom handling
+ * const parsed = parseError(error.message);
+ * // { code: 'LTNS_0100', developerMessage: 'Unauthorized...', translatedMessage: '...' }
+ * ```
+ */
+export declare function useLtErrorTranslation(): UseLtErrorTranslationReturn;

package/dist/runtime/composables/use-lt-error-translation.js

@@ -0,0 +1,133 @@
+import { computed, ref, useState, useNuxtApp, useRuntimeConfig } from "#imports";
+const ERROR_CODE_REGEX = /^#([A-Z_]+_\d+):\s*(.+)$/;
+export function useLtErrorTranslation() {
+  const nuxtApp = useNuxtApp();
+  const runtimeConfig = useRuntimeConfig();
+  const translations = useState(
+    "lt-error-translations",
+    () => ({})
+  );
+  const isLoading = ref(false);
+  const config = runtimeConfig.public?.ltExtensions?.errorTranslation;
+  function t(key, germanFallback) {
+    const i18n = nuxtApp.$i18n;
+    if (!i18n?.t) {
+      return germanFallback;
+    }
+    return i18n.t(key);
+  }
+  function detectLocale() {
+    const i18n = nuxtApp.$i18n;
+    if (i18n?.locale?.value) {
+      return i18n.locale.value;
+    }
+    if (import.meta.client && navigator?.language) {
+      const browserLang = navigator.language.split("-")[0] ?? "de";
+      if (["de", "en"].includes(browserLang)) {
+        return browserLang;
+      }
+    }
+    return config?.defaultLocale || "de";
+  }
+  function getApiBase() {
+    return runtimeConfig.public?.ltExtensions?.auth?.baseURL || "";
+  }
+  async function loadTranslations(locale) {
+    const targetLocale = locale || detectLocale();
+    if (translations.value[targetLocale]) {
+      return;
+    }
+    if (isLoading.value) {
+      return;
+    }
+    isLoading.value = true;
+    try {
+      const apiBase = getApiBase();
+      const response = await $fetch(
+        `${apiBase}/api/i18n/errors/${targetLocale}`
+      );
+      if (response?.errors) {
+        translations.value = {
+          ...translations.value,
+          [targetLocale]: response.errors
+        };
+      }
+    } catch (error) {
+      console.warn(`[LtErrorTranslation] Failed to load translations for ${targetLocale}:`, error);
+    } finally {
+      isLoading.value = false;
+    }
+  }
+  function extractMessage(errorOrMessage) {
+    if (typeof errorOrMessage === "string") {
+      return errorOrMessage;
+    }
+    if (errorOrMessage instanceof Error) {
+      return errorOrMessage.message;
+    }
+    if (typeof errorOrMessage === "object" && errorOrMessage !== null) {
+      const obj = errorOrMessage;
+      return obj.message || obj.error?.message || obj.data?.message || obj.statusMessage || String(obj);
+    }
+    return String(errorOrMessage);
+  }
+  function parseError(errorOrMessage) {
+    const message = extractMessage(errorOrMessage);
+    const match = message.match(ERROR_CODE_REGEX);
+    if (match) {
+      const code = match[1] || "";
+      const developerMessage = match[2] || "";
+      const locale = detectLocale();
+      const localeTranslations = translations.value[locale] || {};
+      const translatedMessage = localeTranslations[code] || developerMessage;
+      return {
+        code,
+        developerMessage,
+        translatedMessage
+      };
+    }
+    return {
+      code: null,
+      developerMessage: message,
+      translatedMessage: message
+    };
+  }
+  function translateError(errorOrMessage) {
+    const parsed = parseError(errorOrMessage);
+    return parsed.translatedMessage;
+  }
+  function showErrorToast(errorOrMessage, title) {
+    if (!import.meta.client) {
+      return;
+    }
+    const parsed = parseError(errorOrMessage);
+    try {
+      nuxtApp.runWithContext(() => {
+        const toastComposable = nuxtApp.useToast || globalThis.useToast;
+        if (typeof toastComposable === "function") {
+          const toast = toastComposable();
+          toast.add({
+            color: "error",
+            title: title || t("lt.error.title", "Fehler"),
+            description: parsed.translatedMessage
+          });
+        } else {
+          console.error("[LtErrorTranslation]", parsed.translatedMessage);
+        }
+      });
+    } catch {
+      console.error("[LtErrorTranslation]", parsed.translatedMessage);
+    }
+  }
+  const currentLocale = computed(() => detectLocale());
+  const isLoaded = computed(() => !!translations.value[currentLocale.value]);
+  return {
+    translateError,
+    parseError,
+    showErrorToast,
+    loadTranslations,
+    isLoaded,
+    isLoading,
+    currentLocale
+  };
+}

package/dist/runtime/lib/auth-client.js

@@ -3,9 +3,9 @@ import { adminClient, twoFactorClient } from "better-auth/client/plugins";
 import { createAuthClient } from "better-auth/vue";
 import { navigateTo } from "#imports";
 import { ltSha256 } from "../utils/crypto.js";
-import { createLtAuthFetch } from "./auth-state.js";
+import { createLtAuthFetch, isLtDevMode } from "./auth-state.js";
 export function createLtAuthClient(config = {}) {
-  const isDev = import.meta.dev || process.env.NODE_ENV === "local";
+  const isDev = isLtDevMode();
   const defaultBaseURL = isDev ? "" : import.meta.env?.VITE_API_URL || process.env.API_URL || "http://localhost:3000";
   const defaultBasePath = isDev ? "/api/iam" : "/iam";
   const {

package/dist/runtime/lib/auth-state.d.ts

@@ -12,6 +12,15 @@
  * The state is persisted in cookies for SSR compatibility.
  */
 import type { LtAuthMode } from "../types/index.js";
+/**
+ * Detects if we're running in development mode at runtime.
+ *
+ * Note: `import.meta.dev` is evaluated at build time and doesn't work
+ * correctly for pre-built modules. This function uses runtime checks instead.
+ *
+ * @returns true if running in development mode
+ */
+export declare function isLtDevMode(): boolean;
 /**
  * Get the current auth mode from cookie
  */

package/dist/runtime/lib/auth-state.js

@@ -1,3 +1,19 @@
+export function isLtDevMode() {
+  if (import.meta.server) {
+    return process.env.NODE_ENV !== "production";
+  }
+  if (typeof window !== "undefined") {
+    const buildId = window.__NUXT__?.config?.app?.buildId;
+    if (buildId === "dev") {
+      return true;
+    }
+    const hostname = window.location?.hostname;
+    if (hostname === "localhost" || hostname === "127.0.0.1") {
+      return true;
+    }
+  }
+  return false;
+}
 export function getLtAuthMode() {
   if (import.meta.server) return "cookie";
   try {
@@ -53,7 +69,7 @@ export function setLtAuthMode(mode) {
   }
 }
 export function getLtApiBase(basePath = "/iam") {
-  const isDev = import.meta.dev;
+  const isDev = isLtDevMode();
   if (isDev) {
     return `/api${basePath}`;
   }

package/dist/runtime/locales/de.json

@@ -11,6 +11,10 @@
       "registerOptionsError": "Konnte Registrierungsoptionen nicht laden",
       "sessionExpired": "Sitzung abgelaufen"
     },
+    "error": {
+      "title": "Fehler",
+      "loadFailed": "Fehlerübersetzungen konnten nicht geladen werden"
+    },
     "share": {
       "copied": "Link kopiert",
       "copiedDescription": "Der Link wurde in die Zwischenablage kopiert."

package/dist/runtime/locales/en.json

@@ -11,6 +11,10 @@
       "registerOptionsError": "Could not load registration options",
       "sessionExpired": "Session expired"
     },
+    "error": {
+      "title": "Error",
+      "loadFailed": "Failed to load error translations"
+    },
     "share": {
       "copied": "Link copied",
       "copiedDescription": "The link has been copied to clipboard."

package/dist/runtime/plugins/auth-interceptor.client.js

@@ -15,8 +15,9 @@ export default (nuxtApp) => {
   ];
   const publicAuthPaths = [.../* @__PURE__ */ new Set([...defaultPublicPaths, ...configuredPublicPaths])];
   function isPublicAuthRoute() {
-    const route = nuxtApp.$router?.currentRoute?.value;
-    if (!route) return false;
+    const router = nuxtApp.$router;
+    const route = router?.currentRoute?.value;
+    if (!route?.path) return false;
     return publicAuthPaths.some((path) => route.path.startsWith(path));
   }
   function isAuthEndpoint(url) {
@@ -56,7 +57,8 @@ export default (nuxtApp) => {
       if (isAuthenticated.value) {
         console.debug("[LtAuth Interceptor] Session expired, logging out...");
         clearUser();
-        const currentPath = nuxtApp.$router?.currentRoute?.value?.fullPath;
+        const router = nuxtApp.$router;
+        const currentPath = router?.currentRoute?.value?.fullPath;
         const redirectQuery = currentPath && currentPath !== loginPath ? `?redirect=${encodeURIComponent(currentPath)}` : "";
         window.location.href = loginPath + redirectQuery;
       }

package/dist/runtime/plugins/error-translation.client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Error Translation Plugin
+ *
+ * Automatically loads error translations on app start.
+ * Provides global helper methods: $ltTranslateError, $ltShowErrorToast
+ */
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugins/error-translation.client.js

@@ -0,0 +1,17 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#imports";
+import { useLtErrorTranslation } from "../composables/use-lt-error-translation.js";
+export default defineNuxtPlugin(async (nuxtApp) => {
+  const runtimeConfig = useRuntimeConfig();
+  const config = runtimeConfig.public?.ltExtensions?.errorTranslation;
+  if (config?.enabled === false) {
+    return;
+  }
+  const { loadTranslations, translateError, showErrorToast } = useLtErrorTranslation();
+  try {
+    await loadTranslations();
+  } catch (error) {
+    console.warn("[LtErrorTranslation] Initial load failed:", error);
+  }
+  nuxtApp.provide("ltTranslateError", translateError);
+  nuxtApp.provide("ltShowErrorToast", showErrorToast);
+});

package/dist/runtime/testing/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Testing Utilities for @lenne.tech/nuxt-extensions
+ *
+ * This module exports Playwright test helpers for E2E testing
+ * of Nuxt applications using @lenne.tech/nuxt-extensions.
+ *
+ * @example
+ * ```typescript
+ * // In your test file
+ * import {
+ *   waitForHydration,
+ *   gotoAndWaitForHydration,
+ *   fillInput,
+ *   generateTestUser,
+ *   generateTOTP,
+ * } from '@lenne.tech/nuxt-extensions/testing';
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { waitForHydration, gotoAndWaitForHydration, waitForURLAndHydration, DEFAULT_HYDRATION_TIMEOUT, fillInput, fillInputs, generateTestUser, generateRandomString, generateTOTP, extractTOTPSecret, parseTOTPUrl, waitForElement, waitForNetworkIdle, hasText, getAllText, type TestUser, } from "./playwright-helpers.js";

package/dist/runtime/testing/index.js

@@ -0,0 +1,17 @@
+export {
+  waitForHydration,
+  gotoAndWaitForHydration,
+  waitForURLAndHydration,
+  DEFAULT_HYDRATION_TIMEOUT,
+  fillInput,
+  fillInputs,
+  generateTestUser,
+  generateRandomString,
+  generateTOTP,
+  extractTOTPSecret,
+  parseTOTPUrl,
+  waitForElement,
+  waitForNetworkIdle,
+  hasText,
+  getAllText
+} from "./playwright-helpers.js";

package/dist/runtime/testing/playwright-helpers.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Playwright Test Helpers for Nuxt Applications
+ *
+ * This module provides reusable test utilities for E2E testing
+ * with Playwright in Nuxt projects using @lenne.tech/nuxt-extensions.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   waitForHydration,
+ *   gotoAndWaitForHydration,
+ *   fillInput,
+ *   generateTestUser,
+ *   generateTOTP,
+ * } from '@lenne.tech/nuxt-extensions/testing';
+ *
+ * test('my test', async ({ page }) => {
+ *   await gotoAndWaitForHydration(page, '/auth/login');
+ *   await fillInput(page, 'input[name="email"]', 'test@example.com');
+ * });
+ * ```
+ */
+import type { Page } from "@playwright/test";
+/**
+ * Default timeout for hydration waiting (in milliseconds)
+ */
+export declare const DEFAULT_HYDRATION_TIMEOUT = 15000;
+/**
+ * Wait for Nuxt hydration to complete
+ *
+ * This is essential for Nuxt SSR applications where Vue components
+ * need to be hydrated before they can respond to interactions.
+ *
+ * @param page - Playwright page object
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait (default: 15000ms)
+ *
+ * @example
+ * ```typescript
+ * await waitForHydration(page);
+ * await page.click('button'); // Now safe to interact
+ * ```
+ */
+export declare function waitForHydration(page: Page, options?: {
+    timeout?: number;
+}): Promise<void>;
+/**
+ * Navigate to URL and wait for Nuxt hydration to complete
+ *
+ * Combines page.goto() with hydration waiting. Use this instead of
+ * page.goto() when you need to interact with Vue components immediately.
+ *
+ * @param page - Playwright page object
+ * @param url - URL to navigate to (relative or absolute)
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait for hydration (default: 15000ms)
+ *
+ * @example
+ * ```typescript
+ * await gotoAndWaitForHydration(page, '/auth/login');
+ * // Page is now hydrated and ready for interaction
+ * ```
+ */
+export declare function gotoAndWaitForHydration(page: Page, url: string, options?: {
+    timeout?: number;
+}): Promise<void>;
+/**
+ * Wait for URL navigation and then Nuxt hydration
+ *
+ * Use after form submissions or actions that trigger navigation.
+ * Ensures both the navigation completes AND the new page is hydrated.
+ *
+ * @param page - Playwright page object
+ * @param url - URL pattern to wait for (string or RegExp)
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait for URL (default: 30000ms)
+ * @param options.hydrationTimeout - Maximum time to wait for hydration (default: 15000ms)
+ *
+ * @example
+ * ```typescript
+ * await page.click('button[type="submit"]');
+ * await waitForURLAndHydration(page, /\/dashboard/);
+ * ```
+ */
+export declare function waitForURLAndHydration(page: Page, url: string | RegExp, options?: {
+    timeout?: number;
+    hydrationTimeout?: number;
+}): Promise<void>;
+/**
+ * Fill an input field with proper Vue 3 reactivity support
+ *
+ * Uses keyboard typing instead of Playwright's fill() to properly
+ * trigger Vue's v-model updates. This is necessary because fill()
+ * sets the value directly without firing input events in some cases.
+ *
+ * @param page - Playwright page object
+ * @param selector - CSS selector for the input element
+ * @param value - Value to type into the input
+ * @param options - Configuration options
+ * @param options.delay - Delay between keystrokes in ms (default: 5)
+ * @param options.clear - Whether to clear existing content (default: true)
+ *
+ * @example
+ * ```typescript
+ * await fillInput(page, 'input[name="email"]', 'test@example.com');
+ * await fillInput(page, '#password', 'secret', { delay: 10 });
+ * ```
+ */
+export declare function fillInput(page: Page, selector: string, value: string, options?: {
+    delay?: number;
+    clear?: boolean;
+}): Promise<void>;
+/**
+ * Fill multiple input fields at once
+ *
+ * Convenience function for filling multiple form fields.
+ *
+ * @param page - Playwright page object
+ * @param fields - Object mapping selectors to values
+ * @param options - Configuration options passed to fillInput
+ *
+ * @example
+ * ```typescript
+ * await fillInputs(page, {
+ *   'input[name="email"]': 'test@example.com',
+ *   'input[name="password"]': 'secret123',
+ * });
+ * ```
+ */
+export declare function fillInputs(page: Page, fields: Record<string, string>, options?: {
+    delay?: number;
+    clear?: boolean;
+}): Promise<void>;
+/**
+ * Test user credentials interface
+ */
+export interface TestUser {
+    email: string;
+    password: string;
+    name: string;
+}
+/**
+ * Generate unique test user credentials
+ *
+ * Creates unique email, password, and name for test isolation.
+ * Each call generates different credentials to avoid test conflicts.
+ *
+ * @param prefix - Prefix for the email address (default: 'e2e')
+ * @returns Object with email, password, and name
+ *
+ * @example
+ * ```typescript
+ * const user = generateTestUser('auth-test');
+ * // { email: 'auth-test-abc123@test.com', password: 'TestPassabc123!', name: 'E2E Test User auth-test' }
+ * ```
+ */
+export declare function generateTestUser(prefix?: string): TestUser;
+/**
+ * Generate a random string for test data
+ *
+ * @param length - Length of the string (default: 8)
+ * @param charset - Characters to use (default: alphanumeric)
+ *
+ * @example
+ * ```typescript
+ * const id = generateRandomString(12);
+ * const code = generateRandomString(6, '0123456789');
+ * ```
+ */
+export declare function generateRandomString(length?: number, charset?: string): string;
+/**
+ * Generate a TOTP code from a secret (RFC 6238)
+ *
+ * Implements the Time-based One-Time Password algorithm for testing
+ * 2FA functionality. Compatible with Google Authenticator and similar apps.
+ *
+ * @param secret - Base32-encoded TOTP secret
+ * @param options - Configuration options
+ * @param options.digits - Number of digits in the code (default: 6)
+ * @param options.period - Time period in seconds (default: 30)
+ * @param options.algorithm - Hash algorithm (default: 'sha1')
+ * @returns 6-digit TOTP code as string
+ *
+ * @example
+ * ```typescript
+ * const secret = 'JBSWY3DPEHPK3PXP';
+ * const code = generateTOTP(secret);
+ * await page.fill('input[name="code"]', code);
+ * ```
+ */
+export declare function generateTOTP(secret: string, options?: {
+    digits?: number;
+    period?: number;
+    algorithm?: "sha1" | "sha256" | "sha512";
+}): string;
+/**
+ * Extract TOTP secret from otpauth:// URL
+ *
+ * Parses the secret parameter from a TOTP QR code URL.
+ *
+ * @param otpauthUrl - The otpauth:// URL (or data URL containing it)
+ * @returns The extracted secret, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const qrSrc = await page.locator('img[alt="QR Code"]').getAttribute('src');
+ * const secret = extractTOTPSecret(qrSrc);
+ * const code = generateTOTP(secret);
+ * ```
+ */
+export declare function extractTOTPSecret(otpauthUrl: string): string | null;
+/**
+ * Extract all parameters from otpauth:// URL
+ *
+ * @param otpauthUrl - The otpauth:// URL
+ * @returns Object with issuer, account, secret, algorithm, digits, period
+ *
+ * @example
+ * ```typescript
+ * const params = parseTOTPUrl(otpauthUrl);
+ * console.log(params.issuer, params.secret);
+ * ```
+ */
+export declare function parseTOTPUrl(otpauthUrl: string): {
+    issuer: string | null;
+    account: string | null;
+    secret: string | null;
+    algorithm: string;
+    digits: number;
+    period: number;
+};
+/**
+ * Wait for an element to be visible and stable
+ *
+ * Useful for waiting for animations to complete or elements to settle.
+ *
+ * @param page - Playwright page object
+ * @param selector - CSS selector for the element
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait (default: 10000ms)
+ * @param options.stable - Wait for element to be stable (default: true)
+ *
+ * @example
+ * ```typescript
+ * await waitForElement(page, '.modal-content');
+ * ```
+ */
+export declare function waitForElement(page: Page, selector: string, options?: {
+    timeout?: number;
+    stable?: boolean;
+}): Promise<void>;
+/**
+ * Wait for network to be idle
+ *
+ * Useful for waiting for all API calls to complete.
+ *
+ * @param page - Playwright page object
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait (default: 30000ms)
+ *
+ * @example
+ * ```typescript
+ * await page.click('button[type="submit"]');
+ * await waitForNetworkIdle(page);
+ * ```
+ */
+export declare function waitForNetworkIdle(page: Page, options?: {
+    timeout?: number;
+}): Promise<void>;
+/**
+ * Check if an element contains specific text
+ *
+ * @param page - Playwright page object
+ * @param selector - CSS selector for the element
+ * @param text - Text to search for
+ * @returns true if text is found
+ *
+ * @example
+ * ```typescript
+ * const hasError = await hasText(page, '.error', 'Invalid email');
+ * ```
+ */
+export declare function hasText(page: Page, selector: string, text: string): Promise<boolean>;
+/**
+ * Get all text content from matching elements
+ *
+ * @param page - Playwright page object
+ * @param selector - CSS selector for the elements
+ * @returns Array of text content
+ *
+ * @example
+ * ```typescript
+ * const errors = await getAllText(page, '.error-message');
+ * ```
+ */
+export declare function getAllText(page: Page, selector: string): Promise<string[]>;

package/dist/runtime/testing/playwright-helpers.js

@@ -0,0 +1,127 @@
+import * as crypto from "crypto";
+export const DEFAULT_HYDRATION_TIMEOUT = 15e3;
+export async function waitForHydration(page, options = {}) {
+  const timeout = options.timeout ?? DEFAULT_HYDRATION_TIMEOUT;
+  await page.waitForFunction(() => window.useNuxtApp?.()?.isHydrating === false, {
+    timeout
+  });
+}
+export async function gotoAndWaitForHydration(page, url, options = {}) {
+  await page.goto(url);
+  await waitForHydration(page, options);
+}
+export async function waitForURLAndHydration(page, url, options = {}) {
+  const { timeout = 3e4, hydrationTimeout } = options;
+  await page.waitForURL(url, { timeout });
+  await waitForHydration(page, { timeout: hydrationTimeout });
+}
+export async function fillInput(page, selector, value, options = {}) {
+  const { delay = 5, clear = true } = options;
+  const locator = page.locator(selector);
+  await locator.click();
+  if (clear) {
+    await page.keyboard.press("Control+a");
+    await page.keyboard.press("Backspace");
+  }
+  await page.keyboard.type(value, { delay });
+}
+export async function fillInputs(page, fields, options = {}) {
+  for (const [selector, value] of Object.entries(fields)) {
+    await fillInput(page, selector, value, options);
+  }
+}
+export function generateTestUser(prefix = "e2e") {
+  const testId = Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+  return {
+    email: `${prefix}-${testId}@test.com`,
+    password: `TestPass${testId}!`,
+    name: `E2E Test User ${prefix}`
+  };
+}
+export function generateRandomString(length = 8, charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789") {
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += charset.charAt(Math.floor(Math.random() * charset.length));
+  }
+  return result;
+}
+export function generateTOTP(secret, options = {}) {
+  const { digits = 6, period = 30, algorithm = "sha1" } = options;
+  const base32Chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+  let bits = "";
+  for (const char of secret.toUpperCase().replace(/=/g, "")) {
+    const val = base32Chars.indexOf(char);
+    if (val === -1) continue;
+    bits += val.toString(2).padStart(5, "0");
+  }
+  const keyBytes = Buffer.alloc(Math.floor(bits.length / 8));
+  for (let i = 0; i < keyBytes.length; i++) {
+    keyBytes[i] = parseInt(bits.slice(i * 8, (i + 1) * 8), 2);
+  }
+  const counter = Math.floor(Date.now() / 1e3 / period);
+  const counterBuffer = Buffer.alloc(8);
+  counterBuffer.writeBigUInt64BE(BigInt(counter));
+  const hmac = crypto.createHmac(algorithm, keyBytes);
+  hmac.update(counterBuffer);
+  const hash = hmac.digest();
+  const offset = (hash[hash.length - 1] ?? 0) & 15;
+  const code = ((hash[offset] ?? 0) & 127) << 24 | ((hash[offset + 1] ?? 0) & 255) << 16 | ((hash[offset + 2] ?? 0) & 255) << 8 | (hash[offset + 3] ?? 0) & 255;
+  const mod = Math.pow(10, digits);
+  return (code % mod).toString().padStart(digits, "0");
+}
+export function extractTOTPSecret(otpauthUrl) {
+  const decoded = decodeURIComponent(otpauthUrl);
+  const match = decoded.match(/secret=([A-Z2-7]+)/i);
+  return match?.[1]?.toUpperCase() ?? null;
+}
+export function parseTOTPUrl(otpauthUrl) {
+  const decoded = decodeURIComponent(otpauthUrl);
+  const pathMatch = decoded.match(/otpauth:\/\/totp\/(?:([^:]+):)?([^?]+)/);
+  const getParam = (name) => {
+    const match = decoded.match(new RegExp(`${name}=([^&]+)`, "i"));
+    return match?.[1] ?? null;
+  };
+  return {
+    issuer: getParam("issuer") ?? pathMatch?.[1] ?? null,
+    account: pathMatch?.[2] ?? null,
+    secret: getParam("secret")?.toUpperCase() ?? null,
+    algorithm: getParam("algorithm") || "SHA1",
+    digits: parseInt(getParam("digits") || "6", 10),
+    period: parseInt(getParam("period") || "30", 10)
+  };
+}
+export async function waitForElement(page, selector, options = {}) {
+  const { timeout = 1e4, stable = true } = options;
+  const locator = page.locator(selector);
+  await locator.waitFor({ state: "visible", timeout });
+  if (stable) {
+    await locator.evaluate((el) => {
+      return new Promise((resolve) => {
+        if (!el.getAnimations || el.getAnimations().length === 0) {
+          resolve();
+          return;
+        }
+        Promise.all(el.getAnimations().map((a) => a.finished)).then(() => resolve());
+      });
+    });
+  }
+}
+export async function waitForNetworkIdle(page, options = {}) {
+  const { timeout = 3e4 } = options;
+  await page.waitForLoadState("networkidle", { timeout });
+}
+export async function hasText(page, selector, text) {
+  const locator = page.locator(selector);
+  const content = await locator.textContent();
+  return content?.includes(text) ?? false;
+}
+export async function getAllText(page, selector) {
+  const locators = page.locator(selector);
+  const count = await locators.count();
+  const texts = [];
+  for (let i = 0; i < count; i++) {
+    const text = await locators.nth(i).textContent();
+    if (text) texts.push(text.trim());
+  }
+  return texts;
+}

package/dist/runtime/types/error.d.ts

@@ -0,0 +1,48 @@
+import type { ComputedRef, Ref } from "vue";
+/**
+ * Backend error translation response format
+ * Matches the response from GET /api/i18n/errors/:locale
+ */
+export interface LtErrorTranslationResponse {
+    errors: Record<string, string>;
+}
+/**
+ * Parsed error from backend
+ * Contains both the original and translated messages
+ */
+export interface LtParsedError {
+    /** Raw error code (e.g., LTNS_0100) or null if no code found */
+    code: string | null;
+    /** Original developer message from the backend */
+    developerMessage: string;
+    /** Translated user-friendly message */
+    translatedMessage: string;
+}
+/**
+ * Error translation module options
+ */
+export interface LtErrorTranslationModuleOptions {
+    /** Enable error translation feature (default: true) */
+    enabled?: boolean;
+    /** Default locale if not detected (default: 'de') */
+    defaultLocale?: string;
+}
+/**
+ * Return type for useLtErrorTranslation composable
+ */
+export interface UseLtErrorTranslationReturn {
+    /** Translate an error message or code to user-friendly message */
+    translateError: (errorOrMessage: unknown) => string;
+    /** Parse a backend error to extract code and messages */
+    parseError: (errorOrMessage: unknown) => LtParsedError;
+    /** Show translated error as toast notification */
+    showErrorToast: (errorOrMessage: unknown, title?: string) => void;
+    /** Manually load translations for a locale */
+    loadTranslations: (locale?: string) => Promise<void>;
+    /** Check if translations are loaded for current locale */
+    isLoaded: ComputedRef<boolean>;
+    /** Check if translations are currently loading */
+    isLoading: Ref<boolean>;
+    /** Current detected locale */
+    currentLocale: ComputedRef<string>;
+}

package/dist/runtime/types/index.d.ts

@@ -1,3 +1,4 @@
 export type { LtAuthClientConfig, LtAuthMode, LtAuthResponse, LtAuthState, LtPasskeyAuthResult, LtPasskeyRegisterResult, LtUser, UseLtAuthReturn, } from "./auth.js";
 export type { LtFileInfo, LtUploadItem, LtUploadOptions, LtUploadProgress, LtUploadStatus, UseLtFileReturn, UseLtTusUploadReturn, } from "./upload.js";
-export type { LtAuthModuleOptions, LtExtensionsModuleOptions, LtExtensionsPublicRuntimeConfig, LtI18nModuleOptions, LtTusModuleOptions, } from "./module.js";
+export type { LtAuthModuleOptions, LtErrorTranslationModuleOptions, LtExtensionsModuleOptions, LtExtensionsPublicRuntimeConfig, LtI18nModuleOptions, LtTusModuleOptions, } from "./module.js";
+export type { LtErrorTranslationResponse, LtParsedError, UseLtErrorTranslationReturn, } from "./error.js";

package/dist/runtime/types/module.d.ts

@@ -42,12 +42,23 @@ export interface LtI18nModuleOptions {
     /** Automatically merge locale files with @nuxtjs/i18n (default: true) */
     autoMerge?: boolean;
 }
+/**
+ * Error translation module configuration options
+ */
+export interface LtErrorTranslationModuleOptions {
+    /** Enable error translation feature (default: true) */
+    enabled?: boolean;
+    /** Default locale if not detected (default: 'de') */
+    defaultLocale?: string;
+}
 /**
  * Main module options for @lenne.tech/nuxt-extensions
  */
 export interface LtExtensionsModuleOptions {
     /** Auth module configuration */
     auth?: LtAuthModuleOptions;
+    /** Error translation configuration */
+    errorTranslation?: LtErrorTranslationModuleOptions;
     /** i18n configuration */
     i18n?: LtI18nModuleOptions;
     /** TUS upload module configuration */
@@ -72,6 +83,10 @@ export interface LtExtensionsPublicRuntimeConfig {
             loginPath: string;
             twoFactorRedirectPath: string;
         };
+        errorTranslation: {
+            enabled: boolean;
+            defaultLocale: string;
+        };
         tus: {
             defaultChunkSize: number;
             defaultEndpoint: string;

package/dist/types.d.mts

@@ -8,6 +8,8 @@ export { type LtAuthClientConfig, type LtAuthMode, type LtAuthResponse, type LtA
 
 export { type LtFileInfo, type LtUploadItem, type LtUploadOptions, type LtUploadProgress, type LtUploadStatus, type UseLtFileReturn, type UseLtTusUploadReturn } from '../dist/runtime/types/upload.js'
 
-export { type LtAuthModuleOptions, type LtExtensionsModuleOptions, type LtExtensionsPublicRuntimeConfig, type LtI18nModuleOptions, type LtTusModuleOptions } from '../dist/runtime/types/module.js'
+export { type LtAuthModuleOptions, type LtErrorTranslationModuleOptions, type LtExtensionsModuleOptions, type LtExtensionsPublicRuntimeConfig, type LtI18nModuleOptions, type LtTusModuleOptions } from '../dist/runtime/types/module.js'
+
+export { type LtErrorTranslationResponse, type LtParsedError, type UseLtErrorTranslationReturn } from '../dist/runtime/types/error.js'
 
 export { type configKey, default, type name, type version } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",
@@ -17,6 +17,10 @@
     ".": {
       "types": "./dist/types.d.mts",
       "import": "./dist/module.mjs"
+    },
+    "./testing": {
+      "types": "./dist/runtime/testing/index.d.ts",
+      "import": "./dist/runtime/testing/index.js"
     }
   },
   "main": "./dist/module.mjs",
@@ -24,6 +28,9 @@
     "*": {
       ".": [
         "./dist/types.d.mts"
+      ],
+      "testing": [
+        "./dist/runtime/testing/index.d.ts"
       ]
     }
   },
@@ -33,6 +40,7 @@
   "scripts": {
     "prepare": "git config core.hooksPath .githooks",
     "prepack": "nuxt-module-build build",
+    "check": "npm run format && npm run lint:fix && npm run test:types && npm run test",
     "dev": "npm run dev:prepare && nuxt dev playground",
     "dev:build": "nuxt build playground",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
@@ -45,13 +53,14 @@
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage",
     "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
-    "release": "npm run format:check && npm run lint && npm run test && npm run prepack"
+    "release": "npm run format:check && npm run lint && npm run test:types && npm run test && npm run prepack"
   },
   "dependencies": {
     "@nuxt/kit": "4.2.2"
   },
   "peerDependencies": {
     "@better-auth/passkey": ">=1.0.0",
+    "@playwright/test": ">=1.0.0",
     "better-auth": ">=1.0.0",
     "nuxt": ">=3.0.0",
     "tus-js-client": ">=4.0.0"
@@ -63,6 +72,9 @@
     "@better-auth/passkey": {
       "optional": true
     },
+    "@playwright/test": {
+      "optional": true
+    },
     "tus-js-client": {
       "optional": true
     }
@@ -70,6 +82,7 @@
   "devDependencies": {
     "@better-auth/passkey": "1.4.10",
     "@nuxt/devtools": "3.1.1",
+    "@playwright/test": "1.57.0",
     "@nuxt/module-builder": "1.0.2",
     "@nuxt/schema": "4.2.2",
     "@nuxt/test-utils": "3.23.0",