docs: add @category tags to public API to prep for supabase docs (#95)

mandarini · web-flow · commit e184b8ec17aa · 2026-07-03T14:55:09.000+03:00
* docs: add @category tags to public API and add nestjs to TypeDoc entry points * docs: add @category tags, fix TypeDoc cross-module links, export options types * docs: some small missing things * docs: add @module for jsr score
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,17 +2,15 @@
 
 ## [1.2.0](https://github.com/supabase/server/compare/server-v1.1.0...server-v1.2.0) (2026-06-17)
 
-
 ### Features
 
-* add NestJS adapter ([#55](https://github.com/supabase/server/issues/55)) ([3052a6b](https://github.com/supabase/server/commit/3052a6b30931f0478bfc4f9dcd25505292b585a9))
-* add support for `HS256` JWKs ([#83](https://github.com/supabase/server/issues/83)) ([67c840d](https://github.com/supabase/server/commit/67c840dc5e8df9374877ca94dc6b6e278e4b13f9))
-
+- add NestJS adapter ([#55](https://github.com/supabase/server/issues/55)) ([3052a6b](https://github.com/supabase/server/commit/3052a6b30931f0478bfc4f9dcd25505292b585a9))
+- add support for `HS256` JWKs ([#83](https://github.com/supabase/server/issues/83)) ([67c840d](https://github.com/supabase/server/commit/67c840dc5e8df9374877ca94dc6b6e278e4b13f9))
 
 ### Bug Fixes
 
-* **docs:** Replace manual context casting with Hono Env type ([#77](https://github.com/supabase/server/issues/77)) ([5ac7ccf](https://github.com/supabase/server/commit/5ac7ccf629c246164659b8c1dc329c3e3066ff14))
-* **test:** lint regression in hono tests ([#79](https://github.com/supabase/server/issues/79)) ([182412b](https://github.com/supabase/server/commit/182412b2f0586fa942a6b6d2662fddf0776da9cf))
+- **docs:** Replace manual context casting with Hono Env type ([#77](https://github.com/supabase/server/issues/77)) ([5ac7ccf](https://github.com/supabase/server/commit/5ac7ccf629c246164659b8c1dc329c3e3066ff14))
+- **test:** lint regression in hono tests ([#79](https://github.com/supabase/server/issues/79)) ([182412b](https://github.com/supabase/server/commit/182412b2f0586fa942a6b6d2662fddf0776da9cf))
 
 ## [1.1.0](https://github.com/supabase/server/compare/server-v1.0.0...server-v1.1.0) (2026-05-19)
 
diff --git a/src/adapters/elysia/index.ts b/src/adapters/elysia/index.ts
@@ -1,6 +1,7 @@
 /**
  * Elysia framework adapter for `@supabase/server`.
  *
+ * @module
  * @packageDocumentation
  */
 
diff --git a/src/adapters/elysia/plugin.ts b/src/adapters/elysia/plugin.ts
@@ -4,6 +4,14 @@ import { createSupabaseContext } from '../../create-supabase-context.js'
 import type { AuthError } from '../../errors.js'
 import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
 
+/**
+ * Wraps an {@link AuthError} as an Elysia-compatible error.
+ *
+ * Discriminate in `onError` via `code === 'SupabaseError'`. The original
+ * `AuthError` is available as the typed `.cause`.
+ *
+ * @category Adapters
+ */
 export class SupabaseError extends Error {
   status: number
   declare cause: AuthError
@@ -23,7 +31,7 @@ export class SupabaseError extends Error {
  * @param config - Auth modes and optional environment overrides. CORS is excluded — use Elysia's CORS utilities.
  * @returns An Elysia plugin that exposes `supabaseContext`.
  *
- * @example App-wide auth via `.use()`
+ * @example App-wide auth via .use()
  * ```ts
  * import { Elysia } from 'elysia'
  * import { withSupabase } from '@supabase/server/adapters/elysia'
@@ -38,7 +46,7 @@ export class SupabaseError extends Error {
  * app.listen(3000)
  * ```
  *
- * @example Per-route auth via scoped `.use()`
+ * @example Per-route auth via scoped .use()
  * ```ts
  * import { Elysia } from 'elysia'
  * import { withSupabase } from '@supabase/server/adapters/elysia'
@@ -55,6 +63,8 @@ export class SupabaseError extends Error {
  *
  * app.listen(3000)
  * ```
+ *
+ * @category Adapters
  */
 // The explicit return type below mirrors Elysia's own generic defaults, which use
 // `{}` literals — switching to `object` or `Record<string, never>` would not satisfy
diff --git a/src/adapters/h3/index.ts b/src/adapters/h3/index.ts
@@ -1,6 +1,7 @@
 /**
  * H3 framework adapter for `@supabase/server`.
  *
+ * @module
  * @packageDocumentation
  */
 
diff --git a/src/adapters/h3/middleware.ts b/src/adapters/h3/middleware.ts
@@ -13,7 +13,7 @@ import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
  * @param config - Auth modes and optional environment overrides. CORS is excluded — use H3's CORS utilities.
  * @returns An H3 middleware.
  *
- * @example App-wide auth via `app.use()`
+ * @example App-wide auth via app.use()
  * ```ts
  * import { H3 } from 'h3'
  * import { withSupabase } from '@supabase/server/adapters/h3'
@@ -29,7 +29,7 @@ import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
  * export default { fetch: app.fetch }
  * ```
  *
- * @example Per-route auth via `defineHandler`
+ * @example Per-route auth via defineHandler
  * ```ts
  * import { defineHandler } from 'h3'
  * import { withSupabase } from '@supabase/server/adapters/h3'
@@ -42,6 +42,8 @@ import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
  *   },
  * })
  * ```
+ *
+ * @category Adapters
  */
 export function withSupabase(
   config?: Omit<WithSupabaseConfig, 'cors'>,
diff --git a/src/adapters/hono/index.ts b/src/adapters/hono/index.ts
@@ -1,6 +1,7 @@
 /**
  * Hono framework adapter for `@supabase/server`.
  *
+ * @module
  * @packageDocumentation
  */
 
diff --git a/src/adapters/hono/middleware.ts b/src/adapters/hono/middleware.ts
@@ -37,6 +37,8 @@ import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
  *
  * export default { fetch: app.fetch }
  * ```
+ *
+ * @category Adapters
  */
 export function withSupabase(
   config?: Omit<WithSupabaseConfig, 'cors'>,
diff --git a/src/adapters/nestjs/decorator.ts b/src/adapters/nestjs/decorator.ts
@@ -32,6 +32,8 @@ import type { SupabaseContext } from '../../types.js'
  *   }
  * }
  * ```
+ *
+ * @category Adapters
  */
 export const SupabaseCtx: (
   data?: keyof SupabaseContext,
diff --git a/src/adapters/nestjs/index.ts b/src/adapters/nestjs/index.ts
@@ -1,6 +1,7 @@
 /**
  * NestJS framework adapter for `@supabase/server`.
  *
+ * @module
  * @packageDocumentation
  */
 
diff --git a/src/adapters/nestjs/middleware.ts b/src/adapters/nestjs/middleware.ts
@@ -81,6 +81,8 @@ function toWebRequest(req: NestRequestLike): Request {
  *   }
  * }
  * ```
+ *
+ * @category Adapters
  */
 export function withSupabase(
   config?: Omit<WithSupabaseConfig, 'cors'>,
diff --git a/src/core/create-admin-client.ts b/src/core/create-admin-client.ts
@@ -14,13 +14,15 @@ import { resolveEnv } from './resolve-env.js'
  * Uses a secret key for authentication, giving full access to all data.
  * Stateless — one client per request.
  *
- * @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified secret key is not found.
+ * @throws {@link index.EnvError} If `SUPABASE_URL` is missing or the specified secret key is not found.
  *
  * @example
  * ```ts
  * const supabaseAdmin = createAdminClient()
  * const { data } = await supabaseAdmin.from('audit_log').insert({ action: 'user_login' })
  * ```
+ *
+ * @category Primitives
  */
 export function createAdminClient<Database = unknown>(
   options?: CreateAdminClientOptions,
diff --git a/src/core/create-context-client.ts b/src/core/create-context-client.ts
@@ -14,7 +14,7 @@ import { resolveEnv } from './resolve-env.js'
  * Configured with a publishable key and (optionally) the caller's JWT,
  * so Row-Level Security policies apply. Stateless — one client per request.
  *
- * @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified publishable key is not found.
+ * @throws {@link index.EnvError} If `SUPABASE_URL` is missing or the specified publishable key is not found.
  *
  * @example
  * ```ts
@@ -24,6 +24,8 @@ import { resolveEnv } from './resolve-env.js'
  * })
  * const { data } = await supabase.rpc('get_my_items')
  * ```
+ *
+ * @category Primitives
  */
 export function createContextClient<Database = unknown>(
   options?: CreateContextClientOptions,
diff --git a/src/core/extract-credentials.ts b/src/core/extract-credentials.ts
@@ -21,6 +21,8 @@ import type { Credentials } from '../types.js'
  * console.log(creds.token)  // "eyJhbGci..." or null
  * console.log(creds.apikey) // "sb-abc123-publishable-..." or null
  * ```
+ *
+ * @category Primitives
  */
 export function extractCredentials(request: Request): Credentials {
   const authHeader = request.headers.get('authorization')
diff --git a/src/core/index.ts b/src/core/index.ts
@@ -1,12 +1,15 @@
 /**
- * Composable primitives for constructing a {@link SupabaseContext}.
+ * Composable primitives for constructing a {@link index.SupabaseContext}.
+ * @module
  * @packageDocumentation
  */
 
 export { resolveEnv } from './resolve-env.js'
 export { extractCredentials } from './extract-credentials.js'
 export { verifyCredentials } from './verify-credentials.js'
+export type { VerifyCredentialsOptions } from './verify-credentials.js'
 export { verifyAuth } from './verify-auth.js'
+export type { VerifyAuthOptions } from './verify-auth.js'
 export { createContextClient } from './create-context-client.js'
 export { createAdminClient } from './create-admin-client.js'
 
diff --git a/src/core/resolve-env.ts b/src/core/resolve-env.ts
@@ -157,6 +157,8 @@ function resolveJwks(): JSONWebKeySet | URL | null {
  * // Override for tests
  * const { data: env } = resolveEnv({ url: 'http://localhost:54321' })
  * ```
+ *
+ * @category Primitives
  */
 export function resolveEnv(
   overrides?: Partial<SupabaseEnv>,
diff --git a/src/core/verify-auth.ts b/src/core/verify-auth.ts
@@ -5,8 +5,9 @@ import { verifyCredentials } from './verify-credentials.js'
 
 /**
  * Options for {@link verifyAuth}.
+ * @category Primitives
  */
-interface VerifyAuthOptions {
+export interface VerifyAuthOptions {
   /**
    * Auth mode(s) to try. Modes are attempted in order — the first match wins.
    *
@@ -55,6 +56,8 @@ interface VerifyAuthOptions {
  *
  * console.log(auth.userClaims!.id) // "d0f1a2b3-..."
  * ```
+ *
+ * @category Primitives
  */
 export async function verifyAuth(
   request: Request,
diff --git a/src/core/verify-credentials.ts b/src/core/verify-credentials.ts
@@ -25,8 +25,9 @@ import { resolveEnv } from './resolve-env.js'
 
 /**
  * Options for {@link verifyCredentials}.
+ * @category Primitives
  */
-interface VerifyCredentialsOptions {
+export interface VerifyCredentialsOptions {
   /**
    * Auth mode(s) to try. Modes are attempted in order — the first match wins.
    *
@@ -94,6 +95,10 @@ function jwtClaimsToUserClaims(jwtClaims: JWTClaims): UserClaims {
 
 const INVALID = Symbol('invalid')
 
+/**
+ * A JWKS key resolver with an accessor for the cached key set.
+ * @category Primitives
+ */
 export type JwksResolver = JWTVerifyGetKey & {
   jwks: () => JSONWebKeySet | undefined
 }
@@ -300,6 +305,8 @@ async function tryMode(
  *   return Response.json({ message: error.message }, { status: error.status })
  * }
  * ```
+ *
+ * @category Primitives
  */
 export async function verifyCredentials(
   credentials: Credentials,
diff --git a/src/create-supabase-context.ts b/src/create-supabase-context.ts
@@ -20,6 +20,8 @@ import { verifyAuth } from './core/verify-auth.js'
  * @param options - Auth modes, environment overrides. The `cors` option is ignored here.
  * @returns `{ data: SupabaseContext, error: null }` on success, `{ data: null, error: AuthError }` on failure.
  *
+ * @category Middleware
+ *
  * @example
  * ```ts
  * const { data: ctx, error } = await createSupabaseContext(request, { auth: 'user' })
diff --git a/src/errors.ts b/src/errors.ts
@@ -16,6 +16,8 @@
  *   }
  * }
  * ```
+ *
+ * @category Errors
  */
 export class EnvError extends Error {
   /** Always `500` — environment errors are server-side issues. */
@@ -37,23 +39,41 @@ export class EnvError extends Error {
   }
 }
 
-/** Generic environment error code. */
+/**
+ * Generic environment error code.
+ * @category Errors
+ */
 export const EnvGenericError = 'ENV_ERROR'
 
-/** `SUPABASE_URL` is not set. */
+/**
+ * `SUPABASE_URL` is not set.
+ * @category Errors
+ */
 export const MissingSupabaseURLError = 'MISSING_SUPABASE_URL'
 
-/** Named publishable key not found in `SUPABASE_PUBLISHABLE_KEYS`. */
+/**
+ * Named publishable key not found in `SUPABASE_PUBLISHABLE_KEYS`.
+ * @category Errors
+ */
 export const MissingPublishableKeyError = 'MISSING_PUBLISHABLE_KEY'
 
-/** No default publishable key found. */
+/**
+ * No default publishable key found.
+ * @category Errors
+ */
 export const MissingDefaultPublishableKeyError =
   'MISSING_DEFAULT_PUBLISHABLE_KEY'
 
-/** Named secret key not found in `SUPABASE_SECRET_KEYS`. */
+/**
+ * Named secret key not found in `SUPABASE_SECRET_KEYS`.
+ * @category Errors
+ */
 export const MissingSecretKeyError = 'MISSING_SECRET_KEY'
 
-/** No default secret key found. */
+/**
+ * No default secret key found.
+ * @category Errors
+ */
 export const MissingDefaultSecretKeyError = 'MISSING_DEFAULT_SECRET_KEY'
 
 const EnvErrorMap = {
@@ -104,6 +124,8 @@ const EnvErrorMap = {
  *   )
  * }
  * ```
+ *
+ * @category Errors
  */
 export class AuthError extends Error {
   /**
@@ -130,13 +152,22 @@ export class AuthError extends Error {
   }
 }
 
-/** Generic authentication error code. */
+/**
+ * Generic authentication error code.
+ * @category Errors
+ */
 export const AuthGenericError = 'AUTH_ERROR'
 
-/** No credential matched any allowed auth mode. */
+/**
+ * No credential matched any allowed auth mode.
+ * @category Errors
+ */
 export const InvalidCredentialsError = 'INVALID_CREDENTIALS'
 
-/** Failed to create a Supabase client after auth succeeded. */
+/**
+ * Failed to create a Supabase client after auth succeeded.
+ * @category Errors
+ */
 export const CreateSupabaseClientError = 'CREATE_SUPABASE_CLIENT_ERROR'
 
 const AuthErrorMap = {
@@ -159,6 +190,8 @@ const AuthErrorMap = {
  * throw Errors[MissingSupabaseURLError]()
  * throw Errors[MissingPublishableKeyError]('mobile')
  * ```
+ *
+ * @category Errors
  */
 export const Errors = {
   ...EnvErrorMap,
diff --git a/src/index.ts b/src/index.ts
@@ -1,5 +1,6 @@
 /**
  * Server-side Supabase utilities for modern runtimes.
+ * @module
  * @packageDocumentation
  */
 
diff --git a/src/peer/supabase-js/index.ts b/src/peer/supabase-js/index.ts
@@ -9,6 +9,7 @@
  * second package — `@supabase/server` becomes a single import surface.
  *
  *
+ * @module
  * @packageDocumentation
  */
 
diff --git a/src/types.ts b/src/types.ts
diff --git a/src/with-supabase.ts b/src/with-supabase.ts
diff --git a/typedoc.json b/typedoc.json

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`/**`
`2`	`2`	* Elysia framework adapter for `@supabase/server`.
`3`	`3`	`*`
	`4`	`+ * @module`
`4`	`5`	`* @packageDocumentation`
`5`	`6`	`*/`
`6`	`7`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`/**`
`2`	`2`	* H3 framework adapter for `@supabase/server`.
`3`	`3`	`*`
	`4`	`+ * @module`
`4`	`5`	`* @packageDocumentation`
`5`	`6`	`*/`
`6`	`7`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`/**`
`2`	`2`	* Hono framework adapter for `@supabase/server`.
`3`	`3`	`*`
	`4`	`+ * @module`
`4`	`5`	`* @packageDocumentation`
`5`	`6`	`*/`
`6`	`7`
Original file line number	Diff line number	Diff line change
`@@ -37,6 +37,8 @@ import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'`
`37`	`37`	`*`
`38`	`38`	`* export default { fetch: app.fetch }`
`39`	`39`	* ```
	`40`	`+ *`
	`41`	`+ * @category Adapters`
`40`	`42`	`*/`
`41`	`43`	`export function withSupabase(`
`42`	`44`	`config?: Omit<WithSupabaseConfig, 'cors'>,`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`/**`
`2`	`2`	* NestJS framework adapter for `@supabase/server`.
`3`	`3`	`*`
	`4`	`+ * @module`
`4`	`5`	`* @packageDocumentation`
`5`	`6`	`*/`
`6`	`7`