@ovixa/auth-client 0.1.0

package/dist/chunk-Y5NJCTZO.js

@@ -0,0 +1,143 @@
+import {
+  OvixaAuthError
+} from "./chunk-UHRF6AFJ.js";
+
+// src/middleware/types.ts
+var DEFAULT_COOKIE_OPTIONS = {
+  accessTokenCookie: "ovixa_access_token",
+  refreshTokenCookie: "ovixa_refresh_token",
+  path: "/",
+  secure: true,
+  httpOnly: true,
+  sameSite: "lax"
+};
+function resolveCookieOptions(options) {
+  return {
+    ...DEFAULT_COOKIE_OPTIONS,
+    ...options
+  };
+}
+function isPublicRoute(path, publicRoutes) {
+  for (const route of publicRoutes) {
+    if (route.endsWith("/*")) {
+      const prefix = route.slice(0, -2);
+      if (path === prefix || path.startsWith(prefix + "/")) {
+        return true;
+      }
+    } else if (route === path) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// src/middleware/core.ts
+async function checkAuth(auth, adapter, cookieOptions, autoRefresh = true) {
+  const options = resolveCookieOptions(cookieOptions);
+  const accessToken = adapter.getCookie(options.accessTokenCookie);
+  const refreshToken = adapter.getCookie(options.refreshTokenCookie);
+  if (!accessToken && !refreshToken) {
+    return {
+      context: createUnauthenticatedContext()
+    };
+  }
+  if (accessToken) {
+    try {
+      const result = await auth.verifyToken(accessToken);
+      const user = {
+        id: result.payload.sub,
+        email: result.payload.email,
+        emailVerified: result.payload.email_verified
+      };
+      const session = {
+        accessToken,
+        refreshToken: refreshToken || "",
+        expiresAt: new Date(result.payload.exp * 1e3)
+      };
+      return {
+        context: {
+          user,
+          session,
+          isAuthenticated: true
+        }
+      };
+    } catch (error) {
+      if (error instanceof OvixaAuthError && error.code === "TOKEN_EXPIRED" && refreshToken && autoRefresh) {
+        return tryRefreshToken(auth, refreshToken);
+      }
+      if (refreshToken && autoRefresh) {
+        return tryRefreshToken(auth, refreshToken);
+      }
+      return {
+        context: createUnauthenticatedContext()
+      };
+    }
+  }
+  if (refreshToken && autoRefresh) {
+    return tryRefreshToken(auth, refreshToken);
+  }
+  return {
+    context: createUnauthenticatedContext()
+  };
+}
+async function tryRefreshToken(auth, refreshToken) {
+  try {
+    const tokens = await auth.refreshToken(refreshToken);
+    const authResult = await auth.toAuthResult(tokens);
+    return {
+      context: {
+        user: authResult.user,
+        session: authResult.session,
+        isAuthenticated: true
+      },
+      newTokens: tokens
+    };
+  } catch {
+    return {
+      context: createUnauthenticatedContext()
+    };
+  }
+}
+function createUnauthenticatedContext() {
+  return {
+    user: null,
+    session: null,
+    isAuthenticated: false
+  };
+}
+function setAuthCookies(adapter, tokens, cookieOptions) {
+  const options = resolveCookieOptions(cookieOptions);
+  const baseOptions = {
+    path: options.path,
+    secure: options.secure,
+    httpOnly: options.httpOnly,
+    sameSite: options.sameSite,
+    domain: options.domain
+  };
+  adapter.setCookie(options.accessTokenCookie, tokens.access_token, {
+    ...baseOptions,
+    maxAge: tokens.expires_in
+  });
+  const refreshMaxAge = options.maxAge ?? 30 * 24 * 60 * 60;
+  adapter.setCookie(options.refreshTokenCookie, tokens.refresh_token, {
+    ...baseOptions,
+    maxAge: refreshMaxAge
+  });
+}
+function clearAuthCookies(adapter, cookieOptions) {
+  const options = resolveCookieOptions(cookieOptions);
+  const deleteOptions = {
+    path: options.path,
+    domain: options.domain
+  };
+  adapter.deleteCookie(options.accessTokenCookie, deleteOptions);
+  adapter.deleteCookie(options.refreshTokenCookie, deleteOptions);
+}
+
+export {
+  isPublicRoute,
+  checkAuth,
+  setAuthCookies,
+  clearAuthCookies
+};
+//# sourceMappingURL=chunk-Y5NJCTZO.js.map

package/dist/chunk-Y5NJCTZO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/middleware/types.ts","../src/middleware/core.ts"],"sourcesContent":["/**\n * Middleware types for @ovixa/auth-client\n *\n * Provides generic adapter interfaces and shared types for framework integrations.\n */\n\nimport type { OvixaAuth, User, Session, TokenResponse } from '../index.js';\n\n/**\n * Cookie configuration options for auth middleware.\n */\nexport interface CookieOptions {\n  /** Name of the access token cookie (default: 'ovixa_access_token') */\n  accessTokenCookie?: string;\n  /** Name of the refresh token cookie (default: 'ovixa_refresh_token') */\n  refreshTokenCookie?: string;\n  /** Cookie path (default: '/') */\n  path?: string;\n  /** Whether to use secure cookies (default: true) */\n  secure?: boolean;\n  /** Whether cookies are HTTP-only (default: true) */\n  httpOnly?: boolean;\n  /** SameSite cookie policy (default: 'lax') */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** Cookie domain (optional, defaults to current domain) */\n  domain?: string;\n  /** Max age for cookies in seconds (optional, defaults to token expiry) */\n  maxAge?: number;\n}\n\n/**\n * Options for setting a cookie.\n */\nexport interface SetCookieOptions {\n  path: string;\n  secure: boolean;\n  httpOnly: boolean;\n  sameSite: 'strict' | 'lax' | 'none';\n  domain?: string;\n  maxAge?: number;\n  expires?: Date;\n}\n\n/**\n * Options for deleting a cookie.\n */\nexport interface DeleteCookieOptions {\n  path: string;\n  domain?: string;\n}\n\n/**\n * Configuration for auth middleware.\n */\nexport interface AuthMiddlewareConfig {\n  /** OvixaAuth client instance */\n  auth: OvixaAuth;\n  /** Cookie configuration options */\n  cookies?: CookieOptions;\n  /** Routes that don't require authentication */\n  publicRoutes?: string[];\n  /** URL to redirect unauthenticated requests (if not set, returns 401) */\n  loginRedirect?: string;\n  /** Whether to automatically refresh expired tokens (default: true) */\n  autoRefresh?: boolean;\n}\n\n/**\n * Authentication context available in request handlers.\n */\nexport interface AuthContext {\n  /** The authenticated user, or null if not authenticated */\n  user: User | null;\n  /** The current session, or null if not authenticated */\n  session: Session | null;\n  /** Whether the request is authenticated */\n  isAuthenticated: boolean;\n}\n\n/**\n * Generic cookie adapter interface.\n *\n * Implement this interface to add support for additional frameworks.\n * The adapter abstracts cookie operations so the core auth logic\n * remains framework-agnostic.\n *\n * @example\n * ```typescript\n * class HonoCookieAdapter implements CookieAdapter {\n *   constructor(private context: HonoContext) {}\n *\n *   getCookie(name: string): string | undefined {\n *     return this.context.get.cookie(name);\n *   }\n *\n *   setCookie(name: string, value: string, options: SetCookieOptions): void {\n *     this.context.cookie(name, value, options);\n *   }\n *\n *   deleteCookie(name: string, options: DeleteCookieOptions): void {\n *     this.context.cookie(name, '', { ...options, maxAge: 0 });\n *   }\n * }\n * ```\n */\nexport interface CookieAdapter {\n  /** Get a cookie value by name */\n  getCookie(name: string): string | undefined;\n  /** Set a cookie with the given value and options */\n  setCookie(name: string, value: string, options: SetCookieOptions): void;\n  /** Delete a cookie */\n  deleteCookie(name: string, options: DeleteCookieOptions): void;\n}\n\n/**\n * Result of authentication check.\n */\nexport interface AuthCheckResult {\n  /** Authentication context */\n  context: AuthContext;\n  /** New tokens if refresh occurred */\n  newTokens?: TokenResponse;\n}\n\n/**\n * Default cookie configuration values.\n */\nexport const DEFAULT_COOKIE_OPTIONS: Required<Omit<CookieOptions, 'domain' | 'maxAge'>> = {\n  accessTokenCookie: 'ovixa_access_token',\n  refreshTokenCookie: 'ovixa_refresh_token',\n  path: '/',\n  secure: true,\n  httpOnly: true,\n  sameSite: 'lax',\n};\n\n/**\n * Resolve cookie options with defaults.\n */\nexport function resolveCookieOptions(\n  options?: CookieOptions\n): Required<Omit<CookieOptions, 'domain' | 'maxAge'>> & Pick<CookieOptions, 'domain' | 'maxAge'> {\n  return {\n    ...DEFAULT_COOKIE_OPTIONS,\n    ...options,\n  };\n}\n\n/**\n * Check if a path matches any of the public routes.\n *\n * Supports:\n * - Exact matches: '/login'\n * - Wildcard suffix: '/api/public/*' matches '/api/public/foo/bar'\n *\n * @param path - The request path to check\n * @param publicRoutes - Array of public route patterns\n * @returns Whether the path is public\n */\nexport function isPublicRoute(path: string, publicRoutes: string[]): boolean {\n  for (const route of publicRoutes) {\n    if (route.endsWith('/*')) {\n      // Wildcard match: '/api/*' matches '/api/foo'\n      const prefix = route.slice(0, -2);\n      if (path === prefix || path.startsWith(prefix + '/')) {\n        return true;\n      }\n    } else if (route === path) {\n      // Exact match\n      return true;\n    }\n  }\n  return false;\n}\n","/**\n * Core authentication logic for middleware.\n *\n * This module provides framework-agnostic authentication utilities\n * used by the Astro and Express middleware implementations.\n */\n\nimport type { OvixaAuth, TokenResponse, User, Session } from '../index.js';\nimport { OvixaAuthError } from '../index.js';\nimport type {\n  CookieAdapter,\n  AuthContext,\n  AuthCheckResult,\n  CookieOptions,\n  SetCookieOptions,\n  DeleteCookieOptions,\n} from './types.js';\nimport { resolveCookieOptions } from './types.js';\n\n/**\n * Check authentication status from cookies.\n *\n * This function:\n * 1. Reads the access token from cookies\n * 2. Attempts to verify the access token\n * 3. If expired and autoRefresh is enabled, attempts to refresh using the refresh token\n * 4. Returns the authentication context and any new tokens\n *\n * @param auth - OvixaAuth client instance\n * @param adapter - Cookie adapter for the framework\n * @param cookieOptions - Cookie configuration\n * @param autoRefresh - Whether to automatically refresh expired tokens\n * @returns Authentication check result with context and optional new tokens\n */\nexport async function checkAuth(\n  auth: OvixaAuth,\n  adapter: CookieAdapter,\n  cookieOptions?: CookieOptions,\n  autoRefresh = true\n): Promise<AuthCheckResult> {\n  const options = resolveCookieOptions(cookieOptions);\n\n  const accessToken = adapter.getCookie(options.accessTokenCookie);\n  const refreshToken = adapter.getCookie(options.refreshTokenCookie);\n\n  // No tokens at all\n  if (!accessToken && !refreshToken) {\n    return {\n      context: createUnauthenticatedContext(),\n    };\n  }\n\n  // Try to verify access token\n  if (accessToken) {\n    try {\n      const result = await auth.verifyToken(accessToken);\n\n      const user: User = {\n        id: result.payload.sub,\n        email: result.payload.email,\n        emailVerified: result.payload.email_verified,\n      };\n\n      const session: Session = {\n        accessToken,\n        refreshToken: refreshToken || '',\n        expiresAt: new Date(result.payload.exp * 1000),\n      };\n\n      return {\n        context: {\n          user,\n          session,\n          isAuthenticated: true,\n        },\n      };\n    } catch (error) {\n      // If token is expired and we have a refresh token, try to refresh\n      if (\n        error instanceof OvixaAuthError &&\n        error.code === 'TOKEN_EXPIRED' &&\n        refreshToken &&\n        autoRefresh\n      ) {\n        return tryRefreshToken(auth, refreshToken);\n      }\n\n      // Token is invalid for another reason (bad signature, etc.)\n      // Try refresh if we have a refresh token\n      if (refreshToken && autoRefresh) {\n        return tryRefreshToken(auth, refreshToken);\n      }\n\n      // No refresh token or refresh disabled, return unauthenticated\n      return {\n        context: createUnauthenticatedContext(),\n      };\n    }\n  }\n\n  // No access token but have refresh token - try to refresh\n  if (refreshToken && autoRefresh) {\n    return tryRefreshToken(auth, refreshToken);\n  }\n\n  return {\n    context: createUnauthenticatedContext(),\n  };\n}\n\n/**\n * Attempt to refresh tokens and return new authentication context.\n */\nasync function tryRefreshToken(auth: OvixaAuth, refreshToken: string): Promise<AuthCheckResult> {\n  try {\n    const tokens = await auth.refreshToken(refreshToken);\n    const authResult = await auth.toAuthResult(tokens);\n\n    return {\n      context: {\n        user: authResult.user,\n        session: authResult.session,\n        isAuthenticated: true,\n      },\n      newTokens: tokens,\n    };\n  } catch {\n    // Refresh failed - return unauthenticated\n    return {\n      context: createUnauthenticatedContext(),\n    };\n  }\n}\n\n/**\n * Create an unauthenticated context.\n */\nfunction createUnauthenticatedContext(): AuthContext {\n  return {\n    user: null,\n    session: null,\n    isAuthenticated: false,\n  };\n}\n\n/**\n * Set authentication cookies after login or token refresh.\n *\n * @param adapter - Cookie adapter for the framework\n * @param tokens - Token response from login/refresh\n * @param cookieOptions - Cookie configuration\n */\nexport function setAuthCookies(\n  adapter: CookieAdapter,\n  tokens: TokenResponse,\n  cookieOptions?: CookieOptions\n): void {\n  const options = resolveCookieOptions(cookieOptions);\n\n  const baseOptions: SetCookieOptions = {\n    path: options.path,\n    secure: options.secure,\n    httpOnly: options.httpOnly,\n    sameSite: options.sameSite,\n    domain: options.domain,\n  };\n\n  // Set access token cookie with expiry based on token\n  adapter.setCookie(options.accessTokenCookie, tokens.access_token, {\n    ...baseOptions,\n    maxAge: tokens.expires_in,\n  });\n\n  // Set refresh token cookie with longer expiry (or custom maxAge)\n  // Refresh tokens typically have longer lifetimes than access tokens\n  // Default to 30 days if no maxAge specified\n  const refreshMaxAge = options.maxAge ?? 30 * 24 * 60 * 60; // 30 days in seconds\n  adapter.setCookie(options.refreshTokenCookie, tokens.refresh_token, {\n    ...baseOptions,\n    maxAge: refreshMaxAge,\n  });\n}\n\n/**\n * Clear authentication cookies on logout.\n *\n * @param adapter - Cookie adapter for the framework\n * @param cookieOptions - Cookie configuration\n */\nexport function clearAuthCookies(adapter: CookieAdapter, cookieOptions?: CookieOptions): void {\n  const options = resolveCookieOptions(cookieOptions);\n\n  const deleteOptions: DeleteCookieOptions = {\n    path: options.path,\n    domain: options.domain,\n  };\n\n  adapter.deleteCookie(options.accessTokenCookie, deleteOptions);\n  adapter.deleteCookie(options.refreshTokenCookie, deleteOptions);\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,498 @@
+import { JWTPayload, JWTHeaderParameters } from 'jose';
+
+/**
+ * @ovixa/auth-client
+ *
+ * Client SDK for Ovixa Auth service.
+ * Provides authentication, token verification, and session management.
+ */
+
+/**
+ * Configuration options for the OvixaAuth client.
+ */
+interface AuthClientConfig {
+    /** The base URL of the Ovixa Auth service */
+    authUrl: string;
+    /** The realm ID to authenticate against */
+    realmId: string;
+    /** Your application's client secret (for server-side use only) */
+    clientSecret?: string;
+    /** Cache duration for JWKS in milliseconds (defaults to 1 hour) */
+    jwksCacheTtl?: number;
+}
+/**
+ * JWT claims for an Ovixa access token.
+ */
+interface AccessTokenPayload extends JWTPayload {
+    /** Subject (user ID) */
+    sub: string;
+    /** User's email address */
+    email: string;
+    /** Whether the user's email has been verified */
+    email_verified: boolean;
+    /** Issued at timestamp */
+    iat: number;
+    /** Expiration timestamp */
+    exp: number;
+    /** Issuer */
+    iss: string;
+    /** Audience (realm ID) */
+    aud: string;
+}
+/**
+ * Result of a successful token verification.
+ */
+interface VerifyResult {
+    /** The decoded token payload */
+    payload: AccessTokenPayload;
+    /** The protected header */
+    protectedHeader: JWTHeaderParameters;
+}
+/**
+ * Token response from the auth service.
+ */
+interface TokenResponse {
+    /** The access token (JWT) */
+    access_token: string;
+    /** The refresh token (JWT) */
+    refresh_token: string;
+    /** Token type (always "Bearer") */
+    token_type: 'Bearer';
+    /** Access token expiration time in seconds */
+    expires_in: number;
+    /** Whether this is a new user (only present in OAuth callback) */
+    is_new_user?: boolean;
+}
+/**
+ * User information extracted from token payload.
+ */
+interface User {
+    /** User ID (UUID) */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** Whether the email has been verified */
+    emailVerified: boolean;
+}
+/**
+ * Session information containing tokens and expiry.
+ */
+interface Session {
+    /** The access token (JWT) */
+    accessToken: string;
+    /** The refresh token for obtaining new access tokens */
+    refreshToken: string;
+    /** When the access token expires */
+    expiresAt: Date;
+}
+/**
+ * Combined authentication result with user and session data.
+ */
+interface AuthResult {
+    /** The authenticated user */
+    user: User;
+    /** The session tokens */
+    session: Session;
+    /** Whether this is a new user (only set for OAuth flows) */
+    isNewUser?: boolean;
+}
+/**
+ * Options for signup.
+ */
+interface SignupOptions {
+    /** User's email address */
+    email: string;
+    /** Password meeting requirements */
+    password: string;
+    /** Optional redirect URI after email verification */
+    redirectUri?: string;
+}
+/**
+ * Response from signup endpoint.
+ */
+interface SignupResponse {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Status message */
+    message: string;
+}
+/**
+ * Options for login.
+ */
+interface LoginOptions {
+    /** User's email address */
+    email: string;
+    /** User's password */
+    password: string;
+}
+/**
+ * Options for email verification.
+ */
+interface VerifyEmailOptions {
+    /** Verification token from email */
+    token: string;
+}
+/**
+ * Options for resending verification email.
+ */
+interface ResendVerificationOptions {
+    /** User's email address */
+    email: string;
+    /** Optional redirect URI after verification */
+    redirectUri?: string;
+}
+/**
+ * Generic success response.
+ */
+interface SuccessResponse {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Optional status message */
+    message?: string;
+}
+/**
+ * Options for forgot password request.
+ */
+interface ForgotPasswordOptions {
+    /** User's email address */
+    email: string;
+    /** Optional redirect URI for password reset page */
+    redirectUri?: string;
+}
+/**
+ * Options for password reset.
+ */
+interface ResetPasswordOptions {
+    /** Reset token from email */
+    token: string;
+    /** New password */
+    password: string;
+}
+/**
+ * Supported OAuth providers.
+ */
+type OAuthProvider = 'google' | 'github';
+/**
+ * Options for generating OAuth URL.
+ */
+interface GetOAuthUrlOptions {
+    /** OAuth provider */
+    provider: OAuthProvider;
+    /** Redirect URI after OAuth completes */
+    redirectUri: string;
+}
+/**
+ * Error thrown by OvixaAuth operations.
+ */
+declare class OvixaAuthError extends Error {
+    readonly code: string;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+/**
+ * OvixaAuth client for authenticating with the Ovixa Auth service.
+ *
+ * @example
+ * ```typescript
+ * const auth = new OvixaAuth({
+ *   authUrl: 'https://auth.ovixa.io',
+ *   realmId: 'your-realm-id',
+ *   clientSecret: 'your-client-secret', // Optional, for server-side use
+ * });
+ *
+ * // Verify a token
+ * const result = await auth.verifyToken(accessToken);
+ * console.log(result.payload.email);
+ *
+ * // Refresh tokens
+ * const tokens = await auth.refreshToken(refreshToken);
+ * ```
+ */
+declare class OvixaAuth {
+    private config;
+    private jwksCache;
+    constructor(config: AuthClientConfig);
+    /** Get the configured auth URL */
+    get authUrl(): string;
+    /** Get the configured realm ID */
+    get realmId(): string;
+    /**
+     * Get the JWKS URL for the auth service.
+     */
+    get jwksUrl(): string;
+    /**
+     * Get the JWKS fetcher, creating a new one if necessary.
+     * The fetcher is cached based on the configured TTL.
+     */
+    private getJwksFetcher;
+    /**
+     * Verify an access token and return the decoded payload.
+     *
+     * This method fetches the public key from the JWKS endpoint (with caching)
+     * and verifies the token's signature and claims.
+     *
+     * @param token - The access token (JWT) to verify
+     * @returns The verified token payload and header
+     * @throws {OvixaAuthError} If verification fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await auth.verifyToken(accessToken);
+     *   console.log('User ID:', result.payload.sub);
+     *   console.log('Email:', result.payload.email);
+     * } catch (error) {
+     *   if (error instanceof OvixaAuthError) {
+     *     console.error('Token verification failed:', error.code);
+     *   }
+     * }
+     * ```
+     */
+    verifyToken(token: string): Promise<VerifyResult>;
+    /**
+     * Refresh an access token using a refresh token.
+     *
+     * This method exchanges a valid refresh token for a new access token
+     * and a new refresh token (token rotation).
+     *
+     * @param refreshToken - The refresh token to exchange
+     * @returns New token response with access and refresh tokens
+     * @throws {OvixaAuthError} If the refresh fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const tokens = await auth.refreshToken(currentRefreshToken);
+     *   // Store the new tokens
+     *   saveTokens(tokens.access_token, tokens.refresh_token);
+     * } catch (error) {
+     *   if (error instanceof OvixaAuthError) {
+     *     // Refresh token is invalid or expired - user must re-authenticate
+     *     redirectToLogin();
+     *   }
+     * }
+     * ```
+     */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    /**
+     * Invalidate the cached JWKS fetcher.
+     * Call this if you need to force a refresh of the public keys.
+     */
+    clearJwksCache(): void;
+    /**
+     * Create a new user account.
+     *
+     * After signup, a verification email is sent. The user must verify their
+     * email before they can log in.
+     *
+     * @param options - Signup options
+     * @returns Signup response indicating success
+     * @throws {OvixaAuthError} If signup fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await auth.signup({
+     *     email: 'user@example.com',
+     *     password: 'SecurePassword123!',
+     *     redirectUri: 'https://myapp.com/verify-callback',
+     *   });
+     *   console.log('Verification email sent!');
+     * } catch (error) {
+     *   if (error instanceof OvixaAuthError) {
+     *     if (error.code === 'EMAIL_ALREADY_EXISTS') {
+     *       console.error('Email is already registered');
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    signup(options: SignupOptions): Promise<SignupResponse>;
+    /**
+     * Authenticate a user with email and password.
+     *
+     * @param options - Login options
+     * @returns Token response with access and refresh tokens
+     * @throws {OvixaAuthError} If login fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const tokens = await auth.login({
+     *     email: 'user@example.com',
+     *     password: 'SecurePassword123!',
+     *   });
+     *   console.log('Logged in!', tokens.access_token);
+     * } catch (error) {
+     *   if (error instanceof OvixaAuthError) {
+     *     if (error.code === 'EMAIL_NOT_VERIFIED') {
+     *       console.error('Please verify your email first');
+     *     } else if (error.code === 'INVALID_CREDENTIALS') {
+     *       console.error('Invalid email or password');
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    login(options: LoginOptions): Promise<TokenResponse>;
+    /**
+     * Verify an email address using a verification token.
+     *
+     * This is the API flow that returns tokens. For browser redirect flow,
+     * use `GET /verify` directly.
+     *
+     * @param options - Verification options
+     * @returns Token response with access and refresh tokens
+     * @throws {OvixaAuthError} If verification fails
+     *
+     * @example
+     * ```typescript
+     * // Get token from URL query params after clicking email link
+     * const token = new URLSearchParams(window.location.search).get('token');
+     *
+     * try {
+     *   const tokens = await auth.verifyEmail({ token });
+     *   console.log('Email verified! Logged in.');
+     * } catch (error) {
+     *   if (error instanceof OvixaAuthError && error.code === 'INVALID_TOKEN') {
+     *     console.error('Invalid or expired verification link');
+     *   }
+     * }
+     * ```
+     */
+    verifyEmail(options: VerifyEmailOptions): Promise<TokenResponse>;
+    /**
+     * Resend a verification email for an unverified account.
+     *
+     * @param options - Resend options
+     * @returns Success response
+     * @throws {OvixaAuthError} If request fails
+     *
+     * @example
+     * ```typescript
+     * await auth.resendVerification({
+     *   email: 'user@example.com',
+     *   redirectUri: 'https://myapp.com/verify-callback',
+     * });
+     * console.log('Verification email sent!');
+     * ```
+     */
+    resendVerification(options: ResendVerificationOptions): Promise<SuccessResponse>;
+    /**
+     * Request a password reset email.
+     *
+     * Note: This endpoint always returns success to prevent email enumeration.
+     *
+     * @param options - Forgot password options
+     * @returns Success response
+     * @throws {OvixaAuthError} If request fails
+     *
+     * @example
+     * ```typescript
+     * await auth.forgotPassword({
+     *   email: 'user@example.com',
+     *   redirectUri: 'https://myapp.com/reset-password',
+     * });
+     * console.log('If the email exists, a reset link has been sent.');
+     * ```
+     */
+    forgotPassword(options: ForgotPasswordOptions): Promise<SuccessResponse>;
+    /**
+     * Reset password using a reset token.
+     *
+     * @param options - Reset password options
+     * @returns Success response
+     * @throws {OvixaAuthError} If reset fails
+     *
+     * @example
+     * ```typescript
+     * // Get token from URL query params
+     * const token = new URLSearchParams(window.location.search).get('token');
+     *
+     * try {
+     *   await auth.resetPassword({
+     *     token,
+     *     password: 'NewSecurePassword123!',
+     *   });
+     *   console.log('Password reset successfully!');
+     * } catch (error) {
+     *   if (error instanceof OvixaAuthError) {
+     *     if (error.code === 'INVALID_TOKEN') {
+     *       console.error('Invalid or expired reset link');
+     *     } else if (error.code === 'WEAK_PASSWORD') {
+     *       console.error('Password does not meet requirements');
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    resetPassword(options: ResetPasswordOptions): Promise<SuccessResponse>;
+    /**
+     * Revoke a refresh token (logout).
+     *
+     * @param refreshToken - The refresh token to revoke
+     * @returns Success response
+     * @throws {OvixaAuthError} If logout fails
+     *
+     * @example
+     * ```typescript
+     * await auth.logout(currentRefreshToken);
+     * // Clear local token storage
+     * localStorage.removeItem('refresh_token');
+     * localStorage.removeItem('access_token');
+     * ```
+     */
+    logout(refreshToken: string): Promise<SuccessResponse>;
+    /**
+     * Generate an OAuth authorization URL.
+     *
+     * Redirect the user to this URL to start the OAuth flow. After authentication,
+     * the user will be redirected back to your `redirectUri` with tokens.
+     *
+     * @param options - OAuth URL options
+     * @returns The full OAuth authorization URL
+     *
+     * @example
+     * ```typescript
+     * const googleAuthUrl = auth.getOAuthUrl({
+     *   provider: 'google',
+     *   redirectUri: 'https://myapp.com/auth/callback',
+     * });
+     *
+     * // Redirect user to start OAuth flow
+     * window.location.href = googleAuthUrl;
+     * ```
+     */
+    getOAuthUrl(options: GetOAuthUrlOptions): string;
+    /**
+     * Transform a token response into an AuthResult with user and session data.
+     *
+     * This method decodes the access token to extract user information and
+     * creates a structured result object.
+     *
+     * @param tokenResponse - The token response from login, verify, or refresh
+     * @returns AuthResult with user and session data
+     * @throws {OvixaAuthError} If the access token cannot be decoded
+     *
+     * @example
+     * ```typescript
+     * const tokens = await auth.login({ email, password });
+     * const result = await auth.toAuthResult(tokens);
+     *
+     * console.log('User ID:', result.user.id);
+     * console.log('Email:', result.user.email);
+     * console.log('Expires at:', result.session.expiresAt);
+     * ```
+     */
+    toAuthResult(tokenResponse: TokenResponse): Promise<AuthResult>;
+    /**
+     * Make an authenticated POST request to the auth service.
+     */
+    private makeRequest;
+    /**
+     * Map HTTP status codes to error codes.
+     */
+    private mapHttpStatusToErrorCode;
+}
+
+export { type AccessTokenPayload, type AuthClientConfig, type AuthResult, type ForgotPasswordOptions, type GetOAuthUrlOptions, type LoginOptions, type OAuthProvider, OvixaAuth, OvixaAuthError, type ResendVerificationOptions, type ResetPasswordOptions, type Session, type SignupOptions, type SignupResponse, type SuccessResponse, type TokenResponse, type User, type VerifyEmailOptions, type VerifyResult };

package/dist/index.js

@@ -0,0 +1,9 @@
+import {
+  OvixaAuth,
+  OvixaAuthError
+} from "./chunk-UHRF6AFJ.js";
+export {
+  OvixaAuth,
+  OvixaAuthError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}