@supabase/auth-js 2.81.2-canary.0 → 2.81.2-canary.2

package/src/lib/errors.ts

@@ -1,6 +1,16 @@
 import { WeakPasswordReasons } from './types'
 import { ErrorCode } from './error-codes'
 
+/**
+ * Base error thrown by Supabase Auth helpers.
+ *
+ * @example
+ * ```ts
+ * import { AuthError } from '@supabase/auth-js'
+ *
+ * throw new AuthError('Unexpected auth error', 500, 'unexpected')
+ * ```
+ */
 export class AuthError extends Error {
   /**
    * Error code associated with the error. Most errors coming from
@@ -27,6 +37,16 @@ export function isAuthError(error: unknown): error is AuthError {
   return typeof error === 'object' && error !== null && '__isAuthError' in error
 }
 
+/**
+ * Error returned directly from the GoTrue REST API.
+ *
+ * @example
+ * ```ts
+ * import { AuthApiError } from '@supabase/auth-js'
+ *
+ * throw new AuthApiError('Invalid credentials', 400, 'invalid_credentials')
+ * ```
+ */
 export class AuthApiError extends AuthError {
   status: number
 
@@ -42,6 +62,20 @@ export function isAuthApiError(error: unknown): error is AuthApiError {
   return isAuthError(error) && error.name === 'AuthApiError'
 }
 
+/**
+ * Wraps non-standard errors so callers can inspect the root cause.
+ *
+ * @example
+ * ```ts
+ * import { AuthUnknownError } from '@supabase/auth-js'
+ *
+ * try {
+ *   await someAuthCall()
+ * } catch (err) {
+ *   throw new AuthUnknownError('Auth failed', err)
+ * }
+ * ```
+ */
 export class AuthUnknownError extends AuthError {
   originalError: unknown
 
@@ -52,6 +86,16 @@ export class AuthUnknownError extends AuthError {
   }
 }
 
+/**
+ * Flexible error class used to create named auth errors at runtime.
+ *
+ * @example
+ * ```ts
+ * import { CustomAuthError } from '@supabase/auth-js'
+ *
+ * throw new CustomAuthError('My custom auth error', 'MyAuthError', 400, 'custom_code')
+ * ```
+ */
 export class CustomAuthError extends AuthError {
   name: string
   status: number
@@ -63,6 +107,16 @@ export class CustomAuthError extends AuthError {
   }
 }
 
+/**
+ * Error thrown when an operation requires a session but none is present.
+ *
+ * @example
+ * ```ts
+ * import { AuthSessionMissingError } from '@supabase/auth-js'
+ *
+ * throw new AuthSessionMissingError()
+ * ```
+ */
 export class AuthSessionMissingError extends CustomAuthError {
   constructor() {
     super('Auth session missing!', 'AuthSessionMissingError', 400, undefined)
@@ -73,18 +127,51 @@ export function isAuthSessionMissingError(error: any): error is AuthSessionMissi
   return isAuthError(error) && error.name === 'AuthSessionMissingError'
 }
 
+/**
+ * Error thrown when the token response is malformed.
+ *
+ * @example
+ * ```ts
+ * import { AuthInvalidTokenResponseError } from '@supabase/auth-js'
+ *
+ * throw new AuthInvalidTokenResponseError()
+ * ```
+ */
 export class AuthInvalidTokenResponseError extends CustomAuthError {
   constructor() {
     super('Auth session or user missing', 'AuthInvalidTokenResponseError', 500, undefined)
   }
 }
 
+/**
+ * Error thrown when email/password credentials are invalid.
+ *
+ * @example
+ * ```ts
+ * import { AuthInvalidCredentialsError } from '@supabase/auth-js'
+ *
+ * throw new AuthInvalidCredentialsError('Email or password is incorrect')
+ * ```
+ */
 export class AuthInvalidCredentialsError extends CustomAuthError {
   constructor(message: string) {
     super(message, 'AuthInvalidCredentialsError', 400, undefined)
   }
 }
 
+/**
+ * Error thrown when implicit grant redirects contain an error.
+ *
+ * @example
+ * ```ts
+ * import { AuthImplicitGrantRedirectError } from '@supabase/auth-js'
+ *
+ * throw new AuthImplicitGrantRedirectError('OAuth redirect failed', {
+ *   error: 'access_denied',
+ *   code: 'oauth_error',
+ * })
+ * ```
+ */
 export class AuthImplicitGrantRedirectError extends CustomAuthError {
   details: { error: string; code: string } | null = null
   constructor(message: string, details: { error: string; code: string } | null = null) {
@@ -108,6 +195,16 @@ export function isAuthImplicitGrantRedirectError(
   return isAuthError(error) && error.name === 'AuthImplicitGrantRedirectError'
 }
 
+/**
+ * Error thrown during PKCE code exchanges.
+ *
+ * @example
+ * ```ts
+ * import { AuthPKCEGrantCodeExchangeError } from '@supabase/auth-js'
+ *
+ * throw new AuthPKCEGrantCodeExchangeError('PKCE exchange failed')
+ * ```
+ */
 export class AuthPKCEGrantCodeExchangeError extends CustomAuthError {
   details: { error: string; code: string } | null = null
 
@@ -126,6 +223,16 @@ export class AuthPKCEGrantCodeExchangeError extends CustomAuthError {
   }
 }
 
+/**
+ * Error thrown when a transient fetch issue occurs.
+ *
+ * @example
+ * ```ts
+ * import { AuthRetryableFetchError } from '@supabase/auth-js'
+ *
+ * throw new AuthRetryableFetchError('Service temporarily unavailable', 503)
+ * ```
+ */
 export class AuthRetryableFetchError extends CustomAuthError {
   constructor(message: string, status: number) {
     super(message, 'AuthRetryableFetchError', status, undefined)
@@ -141,6 +248,16 @@ export function isAuthRetryableFetchError(error: unknown): error is AuthRetryabl
  * weak. Inspect the reasons to identify what password strength rules are
  * inadequate.
  */
+/**
+ * Error thrown when a supplied password is considered weak.
+ *
+ * @example
+ * ```ts
+ * import { AuthWeakPasswordError } from '@supabase/auth-js'
+ *
+ * throw new AuthWeakPasswordError('Password too short', 400, ['min_length'])
+ * ```
+ */
 export class AuthWeakPasswordError extends CustomAuthError {
   /**
    * Reasons why the password is deemed weak.
@@ -158,6 +275,16 @@ export function isAuthWeakPasswordError(error: unknown): error is AuthWeakPasswo
   return isAuthError(error) && error.name === 'AuthWeakPasswordError'
 }
 
+/**
+ * Error thrown when a JWT cannot be verified or parsed.
+ *
+ * @example
+ * ```ts
+ * import { AuthInvalidJwtError } from '@supabase/auth-js'
+ *
+ * throw new AuthInvalidJwtError('Token signature is invalid')
+ * ```
+ */
 export class AuthInvalidJwtError extends CustomAuthError {
   constructor(message: string) {
     super(message, 'AuthInvalidJwtError', 400, 'invalid_jwt')

package/src/lib/locks.ts

@@ -19,6 +19,17 @@ export const internals = {
  * An error thrown when a lock cannot be acquired after some amount of time.
  *
  * Use the {@link #isAcquireTimeout} property instead of checking with `instanceof`.
+ *
+ * @example
+ * ```ts
+ * import { LockAcquireTimeoutError } from '@supabase/auth-js'
+ *
+ * class CustomLockError extends LockAcquireTimeoutError {
+ *   constructor() {
+ *     super('Lock timed out')
+ *   }
+ * }
+ * ```
  */
 export abstract class LockAcquireTimeoutError extends Error {
   public readonly isAcquireTimeout = true
@@ -28,7 +39,27 @@ export abstract class LockAcquireTimeoutError extends Error {
   }
 }
 
+/**
+ * Error thrown when the browser Navigator Lock API fails to acquire a lock.
+ *
+ * @example
+ * ```ts
+ * import { NavigatorLockAcquireTimeoutError } from '@supabase/auth-js'
+ *
+ * throw new NavigatorLockAcquireTimeoutError('Lock timed out')
+ * ```
+ */
 export class NavigatorLockAcquireTimeoutError extends LockAcquireTimeoutError {}
+/**
+ * Error thrown when the process-level lock helper cannot acquire a lock.
+ *
+ * @example
+ * ```ts
+ * import { ProcessLockAcquireTimeoutError } from '@supabase/auth-js'
+ *
+ * throw new ProcessLockAcquireTimeoutError('Lock timed out')
+ * ```
+ */
 export class ProcessLockAcquireTimeoutError extends LockAcquireTimeoutError {}
 
 /**
@@ -55,6 +86,12 @@ export class ProcessLockAcquireTimeoutError extends LockAcquireTimeoutError {}
  *                       will time out after so many milliseconds. An error is
  *                       a timeout if it has `isAcquireTimeout` set to true.
  * @param fn The operation to run once the lock is acquired.
+ * @example
+ * ```ts
+ * await navigatorLock('sync-user', 1000, async () => {
+ *   await refreshSession()
+ * })
+ * ```
  */
 export async function navigatorLock<R>(
   name: string,
@@ -167,6 +204,12 @@ const PROCESS_LOCKS: { [name: string]: Promise<any> } = {}
  *                       will time out after so many milliseconds. An error is
  *                       a timeout if it has `isAcquireTimeout` set to true.
  * @param fn The operation to run once the lock is acquired.
+ * @example
+ * ```ts
+ * await processLock('migrate', 5000, async () => {
+ *   await runMigration()
+ * })
+ * ```
  */
 export async function processLock<R>(
   name: string,

package/src/lib/types.ts

@@ -1675,11 +1675,11 @@ export interface GoTrueAdminOAuthApi {
  */
 export type OAuthAuthorizationClient = {
   /** Unique identifier for the OAuth client (UUID) */
-  client_id: string
+  id: string
   /** Human-readable name of the OAuth client */
-  client_name: string
+  name: string
   /** URI of the OAuth client's website */
-  client_uri: string
+  uri: string
   /** URI of the OAuth client's logo */
   logo_uri: string
 }
@@ -1721,6 +1721,31 @@ export type AuthOAuthConsentResponse = RequestResult<{
   redirect_url: string
 }>
 
+/**
+ * An OAuth grant representing a user's authorization of an OAuth client.
+ * Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+ */
+export type OAuthGrant = {
+  /** OAuth client information */
+  client: OAuthAuthorizationClient
+  /** Array of scopes granted to this client */
+  scopes: string[]
+  /** Timestamp when the grant was created (ISO 8601 date-time) */
+  granted_at: string
+}
+
+/**
+ * Response type for listing user's OAuth grants.
+ * Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+ */
+export type AuthOAuthGrantsResponse = RequestResult<OAuthGrant[]>
+
+/**
+ * Response type for revoking an OAuth grant.
+ * Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+ */
+export type AuthOAuthRevokeGrantResponse = RequestResult<{}>
+
 /**
  * Contains all OAuth 2.1 authorization server user-facing methods.
  * Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
@@ -1767,4 +1792,25 @@ export interface AuthOAuthServerApi {
     authorizationId: string,
     options?: { skipBrowserRedirect?: boolean }
   ): Promise<AuthOAuthConsentResponse>
+
+  /**
+   * Lists all OAuth grants that the authenticated user has authorized.
+   * Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+   *
+   * @returns Response with array of OAuth grants with client information and granted scopes
+   */
+  listGrants(): Promise<AuthOAuthGrantsResponse>
+
+  /**
+   * Revokes a user's OAuth grant for a specific client.
+   * Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+   *
+   * Revocation marks consent as revoked, deletes active sessions for that OAuth client,
+   * and invalidates associated refresh tokens.
+   *
+   * @param options - Revocation options
+   * @param options.clientId - The OAuth client identifier (UUID) to revoke access for
+   * @returns Empty response on successful revocation
+   */
+  revokeGrant(options: { clientId: string }): Promise<AuthOAuthRevokeGrantResponse>
 }

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.81.2-canary.0'
+export const version = '2.81.2-canary.2'