docs(repo): add example snippets

Author: mandarini

packages/core/auth-js/src/GoTrueAdminApi.ts

@@ -45,6 +45,19 @@ export default class GoTrueAdminApi {
   }
   protected fetch: Fetch
 
+  /**
+   * Creates an admin API client that can be used to manage users and OAuth clients.
+   *
+   * @example
+   * ```ts
+   * import { GoTrueAdminApi } from '@supabase/auth-js'
+   *
+   * const admin = new GoTrueAdminApi({
+   *   url: 'https://xyzcompany.supabase.co/auth/v1',
+   *   headers: { Authorization: `Bearer ${process.env.SUPABASE_SERVICE_ROLE_KEY}` },
+   * })
+   * ```
+   */
   constructor({
     url = '',
     headers = {},

packages/core/auth-js/src/GoTrueClient.ts

@@ -275,6 +275,17 @@ export default class GoTrueClient {
 
   /**
    * Create a new client for use in the browser.
+   *
+   * @example
+   * ```ts
+   * import { GoTrueClient } from '@supabase/auth-js'
+   *
+   * const auth = new GoTrueClient({
+   *   url: 'https://xyzcompany.supabase.co/auth/v1',
+   *   headers: { apikey: 'public-anon-key' },
+   *   storageKey: 'supabase-auth',
+   * })
+   * ```
    */
   constructor(options: GoTrueClientOptions) {
     const settings = { ...DEFAULT_OPTIONS, ...options }

packages/core/auth-js/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')

packages/core/auth-js/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 {}
 
 /**

packages/core/functions-js/src/types.ts

@@ -15,6 +15,18 @@ export interface FunctionsResponseFailure {
 }
 export type FunctionsResponse<T> = FunctionsResponseSuccess<T> | FunctionsResponseFailure
 
+/**
+ * Base error for Supabase Edge Function invocations.
+ *
+ * @example
+ * ```ts
+ * import { FunctionsError } from '@supabase/functions-js'
+ *
+ * throw new FunctionsError('Unexpected error invoking function', 'FunctionsError', {
+ *   requestId: 'abc123',
+ * })
+ * ```
+ */
 export class FunctionsError extends Error {
   context: any
   constructor(message: string, name = 'FunctionsError', context?: any) {
@@ -24,18 +36,48 @@ export class FunctionsError extends Error {
   }
 }
 
+/**
+ * Error thrown when the network request to an Edge Function fails.
+ *
+ * @example
+ * ```ts
+ * import { FunctionsFetchError } from '@supabase/functions-js'
+ *
+ * throw new FunctionsFetchError({ requestId: 'abc123' })
+ * ```
+ */
 export class FunctionsFetchError extends FunctionsError {
   constructor(context: any) {
     super('Failed to send a request to the Edge Function', 'FunctionsFetchError', context)
   }
 }
 
+/**
+ * Error thrown when the Supabase relay cannot reach the Edge Function.
+ *
+ * @example
+ * ```ts
+ * import { FunctionsRelayError } from '@supabase/functions-js'
+ *
+ * throw new FunctionsRelayError({ region: 'us-east-1' })
+ * ```
+ */
 export class FunctionsRelayError extends FunctionsError {
   constructor(context: any) {
     super('Relay Error invoking the Edge Function', 'FunctionsRelayError', context)
   }
 }
 
+/**
+ * Error thrown when the Edge Function returns a non-2xx status code.
+ *
+ * @example
+ * ```ts
+ * import { FunctionsHttpError } from '@supabase/functions-js'
+ *
+ * throw new FunctionsHttpError({ status: 500 })
+ * ```
+ */
 export class FunctionsHttpError extends FunctionsError {
   constructor(context: any) {
     super('Edge Function returned a non-2xx status code', 'FunctionsHttpError', context)

packages/core/postgrest-js/src/PostgrestBuilder.ts

@@ -28,6 +28,17 @@ export default abstract class PostgrestBuilder<
   protected fetch: Fetch
   protected isMaybeSingle: boolean
 
+  /**
+   * @example
+   * ```ts
+   * import PostgrestQueryBuilder from '@supabase/postgrest-js'
+   *
+   * const builder = new PostgrestQueryBuilder(
+   *   new URL('https://xyzcompany.supabase.co/rest/v1/users'),
+   *   { headers: new Headers({ apikey: 'public-anon-key' }) }
+   * )
+   * ```
+   */
   constructor(builder: {
     method: 'GET' | 'HEAD' | 'POST' | 'PATCH' | 'DELETE'
     url: URL

packages/core/postgrest-js/src/PostgrestClient.ts

@@ -48,6 +48,15 @@ export default class PostgrestClient<
    * @param options.headers - Custom headers
    * @param options.schema - Postgres schema to switch to
    * @param options.fetch - Custom fetch
+   * @example
+   * ```ts
+   * import PostgrestClient from '@supabase/postgrest-js'
+   *
+   * const postgrest = new PostgrestClient('https://xyzcompany.supabase.co/rest/v1', {
+   *   headers: { apikey: 'public-anon-key' },
+   *   schema: 'public',
+   * })
+   * ```
    */
   constructor(
     url: string,