docs: add titles to examples (#98)

Author: mandarini

CHANGELOG.md

@@ -2,10 +2,9 @@
 
 ## [1.3.1](https://github.com/supabase/server/compare/server-v1.3.0...server-v1.3.1) (2026-07-03)
 
-
 ### Bug Fixes
 
-* expand [@module](https://github.com/module) comment to restore rich JSR overview ([#96](https://github.com/supabase/server/issues/96)) ([a41aeeb](https://github.com/supabase/server/commit/a41aeebd59ef99ca04bd8bbed859ab046b5de61d))
+- expand [@module](https://github.com/module) comment to restore rich JSR overview ([#96](https://github.com/supabase/server/issues/96)) ([a41aeeb](https://github.com/supabase/server/commit/a41aeebd59ef99ca04bd8bbed859ab046b5de61d))
 
 ## [1.3.0](https://github.com/supabase/server/compare/server-v1.2.0...server-v1.3.0) (2026-07-03)
 

jsr.json

@@ -11,14 +11,7 @@
     "./adapters/nestjs": "./src/adapters/nestjs/index.ts"
   },
   "publish": {
-    "include": [
-      "src/**/*.ts",
-      "README.md",
-      "LICENSE"
-    ],
-    "exclude": [
-      "src/**/*.test.ts",
-      "src/**/*.spec.ts"
-    ]
+    "include": ["src/**/*.ts", "README.md", "LICENSE"],
+    "exclude": ["src/**/*.test.ts", "src/**/*.spec.ts"]
   }
 }

src/adapters/hono/middleware.ts

@@ -1,6 +1,6 @@
 import type { MiddlewareHandler } from 'hono'
-import { HTTPException } from 'hono/http-exception'
 import { createMiddleware } from 'hono/factory'
+import { HTTPException } from 'hono/http-exception'
 
 import { createSupabaseContext } from '../../create-supabase-context.js'
 import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
@@ -14,7 +14,7 @@ import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
  * @param config - Auth modes and optional environment overrides. CORS is excluded — use Hono's `cors()`.
  * @returns A Hono middleware that sets `c.var.supabaseContext`.
  *
- * @example
+ * @example App-wide auth via app.use()
  * ```ts
  * import { Hono } from 'hono'
  * import { withSupabase } from '@supabase/server/adapters/hono'

src/adapters/nestjs/decorator.ts

@@ -12,7 +12,7 @@ import type { SupabaseContext } from '../../types.js'
  * by `withSupabase()`. Pass a key (e.g. `'supabase'`, `'userClaims'`) to pull
  * a single field, or no argument to receive the whole context.
  *
- * @example
+ * @example Injecting the context into a route handler
  * ```ts
  * import { Controller, Get, UseGuards } from '@nestjs/common'
  * import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'

src/core/create-admin-client.ts

@@ -16,7 +16,7 @@ import { resolveEnv } from './resolve-env.js'
  *
  * @throws {@link index.EnvError} If `SUPABASE_URL` is missing or the specified secret key is not found.
  *
- * @example
+ * @example Basic usage
  * ```ts
  * const supabaseAdmin = createAdminClient()
  * const { data } = await supabaseAdmin.from('audit_log').insert({ action: 'user_login' })

src/core/create-context-client.ts

@@ -16,7 +16,7 @@ import { resolveEnv } from './resolve-env.js'
  *
  * @throws {@link index.EnvError} If `SUPABASE_URL` is missing or the specified publishable key is not found.
  *
- * @example
+ * @example With verified auth
  * ```ts
  * const { data: auth } = await verifyAuth(request, { auth: 'user' })
  * const supabase = createContextClient({

src/core/extract-credentials.ts

@@ -13,7 +13,7 @@ import type { Credentials } from '../types.js'
  * @param request - The incoming HTTP request.
  * @returns The extracted {@link Credentials}. Fields are `null` when the corresponding header is absent.
  *
- * @example
+ * @example Basic usage
  * ```ts
  * import { extractCredentials } from '@supabase/server/core'
  *

src/core/resolve-env.ts

@@ -1,6 +1,6 @@
-import { EnvError, Errors, MissingSupabaseURLError } from '../errors.js'
 import type { JSONWebKeySet } from 'jose'
 
+import { EnvError, Errors, MissingSupabaseURLError } from '../errors.js'
 import type { SupabaseEnv } from '../types.js'
 
 /**
@@ -149,7 +149,7 @@ function resolveJwks(): JSONWebKeySet | URL | null {
  * @param overrides - Partial values that take precedence over env vars.
  * @returns `{ data: SupabaseEnv, error: null }` on success, `{ data: null, error: EnvError }` on failure.
  *
- * @example
+ * @example Reading and overriding env vars
  * ```ts
  * const { data: env, error } = resolveEnv()
  * if (error) throw error

src/core/verify-auth.ts

@@ -42,7 +42,7 @@ export interface VerifyAuthOptions {
  *   - On success: `{ data: AuthResult, error: null }`
  *   - On failure: `{ data: null, error: AuthError }`
  *
- * @example
+ * @example User auth
  * ```ts
  * import { verifyAuth } from '@supabase/server/core'
  *

src/core/verify-credentials.ts

@@ -19,9 +19,9 @@ import type {
   SupabaseEnv,
   UserClaims,
 } from '../types.js'
+import { resolveEnv } from './resolve-env.js'
 import { resolveAuthOption } from './utils/deprecation.js'
 import { timingSafeEqual } from './utils/timing-safe-equal.js'
-import { resolveEnv } from './resolve-env.js'
 
 /**
  * Options for {@link verifyCredentials}.
@@ -295,7 +295,7 @@ async function tryMode(
  * @param options - Allowed auth modes and optional env overrides.
  * @returns `{ data: AuthResult, error: null }` on success, `{ data: null, error: AuthError }` on failure.
  *
- * @example
+ * @example Multiple auth modes
  * ```ts
  * const credentials = extractCredentials(request)
  * const { data: auth, error } = await verifyCredentials(credentials, {