next-supa-utils 0.1.0 → 0.1.4

package/README.md

@@ -16,47 +16,24 @@
 
 ---
 
-## Why?
+## 🚀 Why Use This Over Raw `@supabase/ssr`?
 
-Every Next.js + Supabase project ends up with the same boilerplate:
+If you use `@supabase/ssr` directly, you have to write boilerplate for *every* environment. **next-supa-utils** eliminates this entirely:
 
-- Creating Supabase clients with cookie handling for middleware, server components, and client components
-- Writing try/catch wrappers around every server action
-- Manually checking auth state in middleware and redirecting
+1. **One-Line Middleware**: No more manually copying the 40-line chunking/cookie-setting logic from the Supabase docs. Just pass your routes to `withSupaAuth()`.
+2. **Type-Safe Server Actions**: Stop writing `try/catch` and `cookies().getAll()` in every server action. `createAction()` handles it automatically and forces you to check for errors.
+3. **Instant Client Hooks**: `useSupaUser()` and `useSupaSession()` wrap `createBrowserClient`, fetch the initial state, *and* subscribe to real-time `onAuthStateChange` events out of the box.
+4. **App Router Ready**: Strictly separated entry points (`/client` and `/server`) guarantee you won't accidentally import server code into client components.
 
-**next-supa-utils** extracts these patterns into a single, type-safe library with separate entry points for client and server code — fully compatible with the Next.js App Router architecture.
-
-## Features
-
-- 🔐 **`withSupaAuth`** — Drop-in middleware for route protection with redirect support
-- ⚡ **`createAction`** — Higher-order function that wraps server actions with automatic Supabase client creation and error handling
-- 👤 **`useSupaUser`** — React hook for real-time user state with auth change subscriptions
-- 🔑 **`useSupaSession`** — React hook for real-time session state
-- 🧩 **Separate entry points** — `next-supa-utils/client` and `next-supa-utils/server` to respect the `"use client"` boundary
-- 📦 **Dual format** — Ships ESM and CJS with full TypeScript declarations
-
-## Installation
+## 📦 Installation
 
 ```bash
 npm install next-supa-utils
 ```
 
-### Peer Dependencies
+*Requires `react >=18`, `next >=14`, `@supabase/supabase-js ^2`, and `@supabase/ssr >=0.5`.*
 
-Make sure you have the following installed in your project:
-
-```bash
-npm install react next @supabase/supabase-js @supabase/ssr
-```
-
-| Package | Version |
-|---|---|
-| `react` | `>=18` |
-| `next` | `>=14` |
-| `@supabase/supabase-js` | `^2.0.0` |
-| `@supabase/ssr` | `>=0.5.0` |
-
-## Environment Variables
+### Environment Variables
 
 Add these to your `.env.local`:
 
@@ -65,73 +42,61 @@ NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
 NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
 ```
 
-Both variables are required. All helpers in this library read from these environment variables automatically.
-
 ---
 
-## Quick Start
+## ⚡ Quick Start
 
-### 1. Protect Routes with Middleware
+### 1. Middleware (Route Protection in 1 Line)
+
+Protect your routes and auto-refresh sessions without copying boilerplate.
 
 ```ts
 // middleware.ts
 import { withSupaAuth } from "next-supa-utils/server";
 
 export default withSupaAuth({
-  protectedRoutes: ["/dashboard", "/admin", "/settings"],
+  protectedRoutes: ["/dashboard", "/admin"],
   redirectTo: "/login",
-  publicRoutes: ["/admin/login"],
 });
 
-export const config = {
-  matcher: [
-    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
-  ],
-};
+export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
 ```
 
-### 2. Create Type-Safe Server Actions
+### 2. Server Actions (No More Try/Catch)
+
+Automatically initializes the server client with cookies and returns a type-safe `{ data, error }` object.
 
 ```ts
-// app/actions/profile.ts
+// app/actions.ts
 "use server";
 import { createAction } from "next-supa-utils/server";
 
 export const getProfile = createAction(async (supabase, userId: string) => {
-  const { data, error } = await supabase
-    .from("profiles")
-    .select("*")
-    .eq("id", userId)
-    .single();
-
-  if (error) throw error;
+  const { data, error } = await supabase.from("profiles").select().eq("id", userId).single();
+  if (error) throw error; // Handled automatically!
   return data;
 });
 ```
 
 ```tsx
-// Usage in any component
-const result = await getProfile("user-uuid");
-
-if (result.error) {
-  console.error(result.error.message);
-} else {
-  console.log(result.data);
-}
+// Usage
+const { data, error } = await getProfile("123");
+if (error) console.error(error.message);
 ```
 
-### 3. Use Auth State in Client Components
+### 3. Client Components (Real-Time User State)
+
+Get the user and listen to auth changes immediately.
 
 ```tsx
 "use client";
 import { useSupaUser } from "next-supa-utils/client";
 
 export default function Avatar() {
-  const { user, loading, error } = useSupaUser();
+  const { user, loading } = useSupaUser();
 
-  if (loading) return <p>Loading…</p>;
-  if (error) return <p>Error: {error.message}</p>;
-  if (!user) return <p>Not signed in</p>;
+  if (loading) return <p>Loading...</p>;
+  if (!user) return <p>Please sign in</p>;
 
   return <p>Hello, {user.email}!</p>;
 }
@@ -307,6 +272,31 @@ src/
 | `next-supa-utils/server` | Server Components, Middleware, Server Actions | `withSupaAuth`, `createAction` |
 | `next-supa-utils` | Anywhere | `handleSupaError`, all types |
 
+## Changelog
+
+### v0.1.3
+
+- **🔐 RBAC Support** — `withSupaAuth` now supports **role-based access control**.
+  - New `RouteConfig` type: define `allowedRoles` per route (e.g. `["admin", "editor"]`).
+  - New `MiddlewareOptions` replaces the old `SupaAuthConfig`.
+  - New `roleExtractor` option: read roles from `user_metadata`, `app_metadata`, or a custom function.
+  - Wildcard path matching supported (e.g. `"/admin/:path*"`).
+  - Unauthorized users are redirected with `?error=forbidden&next=<path>`.
+- **⚠️ Breaking:** `SupaAuthConfig` type removed. Use `MiddlewareOptions` with `routes: RouteConfig[]` instead.
+
+### v0.1.0
+
+- 🎉 **Initial release**
+- `withSupaAuth` — Middleware helper for route protection with session refresh.
+- `createAction` — Type-safe server action wrapper with automatic `{ data, error }` responses.
+- `useSupaUser` — React hook for real-time user state.
+- `useSupaSession` — React hook for real-time session state.
+- `handleSupaError` — Universal error normalizer.
+- Multi-entry package: `next-supa-utils/client`, `next-supa-utils/server`.
+- Dual format output (ESM + CJS) with TypeScript declarations.
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/server/index.cjs

@@ -28,13 +28,41 @@ module.exports = __toCommonJS(server_exports);
 // src/server/middleware/withSupaAuth.ts
 var import_ssr = require("@supabase/ssr");
 var import_server = require("next/server");
-function withSupaAuth(config) {
+function matchPath(pattern, pathname) {
+  if (pattern.includes(":path*")) {
+    const prefix = pattern.replace(/:path\*$/, "").replace(/\/$/, "");
+    return pathname === prefix || pathname.startsWith(prefix + "/");
+  }
+  return pathname === pattern || pathname.startsWith(pattern + "/");
+}
+function findMatchingRoute(routes, pathname) {
+  return routes.find((route) => matchPath(route.path, pathname));
+}
+function extractRole(user, extractor) {
+  if (typeof extractor === "function") {
+    return extractor(user);
+  }
+  const source = extractor === "app_metadata" ? user.app_metadata : user.user_metadata;
+  const raw = source?.role;
+  if (typeof raw === "string") return raw;
+  if (Array.isArray(raw) && raw.every((r) => typeof r === "string")) {
+    return raw;
+  }
+  return void 0;
+}
+function hasRequiredRole(userRole, allowedRoles) {
+  if (!allowedRoles || allowedRoles.length === 0) return true;
+  if (!userRole) return false;
+  const roles = Array.isArray(userRole) ? userRole : [userRole];
+  return roles.some((r) => allowedRoles.includes(r));
+}
+function withSupaAuth(options) {
   const {
-    protectedRoutes,
+    routes,
     redirectTo = "/login",
-    publicRoutes = [],
+    roleExtractor = "user_metadata",
     onAuthSuccess
-  } = config;
+  } = options;
   return async function middleware(request) {
     let response = import_server.NextResponse.next({
       request: { headers: request.headers }
@@ -57,8 +85,8 @@ function withSupaAuth(config) {
             request.cookies.set(name, value);
           });
           response = import_server.NextResponse.next({ request });
-          cookiesToSet.forEach(({ name, value, options }) => {
-            response.cookies.set(name, value, options);
+          cookiesToSet.forEach(({ name, value, options: options2 }) => {
+            response.cookies.set(name, value, options2);
           });
         }
       }
@@ -67,22 +95,28 @@ function withSupaAuth(config) {
       data: { user }
     } = await supabase.auth.getUser();
     const { pathname } = request.nextUrl;
-    const isPublicRoute = publicRoutes.some(
-      (route) => pathname.startsWith(route)
-    );
-    if (isPublicRoute) {
+    const matchedRoute = findMatchingRoute(routes, pathname);
+    if (!matchedRoute) {
       return response;
     }
-    const isProtectedRoute = protectedRoutes.some(
-      (route) => pathname.startsWith(route)
-    );
-    if (isProtectedRoute && !user) {
+    if (!user) {
       const loginUrl = new URL(redirectTo, request.url);
       loginUrl.searchParams.set("next", pathname);
       return import_server.NextResponse.redirect(loginUrl);
     }
-    if (user && onAuthSuccess) {
-      await onAuthSuccess({ id: user.id, email: user.email ?? void 0 });
+    const userRole = extractRole(user, roleExtractor);
+    if (!hasRequiredRole(userRole, matchedRoute.allowedRoles)) {
+      const forbiddenUrl = new URL(redirectTo, request.url);
+      forbiddenUrl.searchParams.set("error", "forbidden");
+      forbiddenUrl.searchParams.set("next", pathname);
+      return import_server.NextResponse.redirect(forbiddenUrl);
+    }
+    if (onAuthSuccess) {
+      await onAuthSuccess({
+        id: user.id,
+        email: user.email ?? void 0,
+        role: userRole
+      });
     }
     return response;
   };

package/dist/server/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/server/index.ts","../../src/server/middleware/withSupaAuth.ts","../../src/server/actions/actionWrapper.ts","../../src/shared/utils/error-handler.ts"],"sourcesContent":["// ── Server entry point ──────────────────────────────────────────────\n// This module should ONLY be imported in server-side contexts:\n// middleware.ts, Server Components, Server Actions, Route Handlers.\n\nexport { withSupaAuth } from \"./middleware/withSupaAuth\";\nexport { createAction } from \"./actions/actionWrapper\";\n\n// Re-export types consumers commonly need alongside server helpers.\nexport type { SupaAuthConfig, ActionResponse, SupaError } from \"../types\";\n","import { createServerClient, type CookieOptions } from \"@supabase/ssr\";\nimport { NextResponse, type NextRequest } from \"next/server\";\n\nimport type { SupaAuthConfig } from \"../../types\";\n\n/**\n * Create a Next.js middleware handler that protects routes based on\n * Supabase authentication state.\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { withSupaAuth } from \"next-supa-utils/server\";\n *\n * export default withSupaAuth({\n *   protectedRoutes: [\"/dashboard\", \"/admin\"],\n *   redirectTo: \"/login\",\n *   publicRoutes: [\"/admin/login\"],\n * });\n *\n * export const config = {\n *   matcher: [\"/((?!_next/static|_next/image|favicon.ico|.*\\\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)\"],\n * };\n * ```\n */\nexport function withSupaAuth(config: SupaAuthConfig) {\n  const {\n    protectedRoutes,\n    redirectTo = \"/login\",\n    publicRoutes = [],\n    onAuthSuccess,\n  } = config;\n\n  return async function middleware(request: NextRequest): Promise<NextResponse> {\n    // ── 1. Create a mutable response so Supabase can set cookies ──\n    let response = NextResponse.next({\n      request: { headers: request.headers },\n    });\n\n    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;\n    const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;\n\n    if (!supabaseUrl || !supabaseAnonKey) {\n      console.error(\n        \"[next-supa-utils] Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.\",\n      );\n      return response;\n    }\n\n    // ── 2. Initialize server client with middleware cookie helpers ─\n    const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n      cookies: {\n        getAll() {\n          return request.cookies.getAll();\n        },\n        setAll(cookiesToSet: { name: string; value: string; options?: CookieOptions }[]) {\n          // Forward cookies to the request so downstream server\n          // components can read the updated session.\n          cookiesToSet.forEach(({ name, value }) => {\n            request.cookies.set(name, value);\n          });\n\n          // Re-create the response so it carries the updated request.\n          response = NextResponse.next({ request });\n\n          // Set cookies on the outgoing response so the browser\n          // stores the refreshed tokens.\n          cookiesToSet.forEach(({ name, value, options }) => {\n            response.cookies.set(name, value, options);\n          });\n        },\n      },\n    });\n\n    // ── 3. Refresh session (required to keep tokens alive) ────────\n    const {\n      data: { user },\n    } = await supabase.auth.getUser();\n\n    const { pathname } = request.nextUrl;\n\n    // ── 4. Check if current path matches a public override ────────\n    const isPublicRoute = publicRoutes.some((route) =>\n      pathname.startsWith(route),\n    );\n\n    if (isPublicRoute) {\n      return response;\n    }\n\n    // ── 5. Check if current path requires authentication ──────────\n    const isProtectedRoute = protectedRoutes.some((route) =>\n      pathname.startsWith(route),\n    );\n\n    if (isProtectedRoute && !user) {\n      const loginUrl = new URL(redirectTo, request.url);\n      // Preserve the originally-requested URL so the app can redirect\n      // back after login.\n      loginUrl.searchParams.set(\"next\", pathname);\n      return NextResponse.redirect(loginUrl);\n    }\n\n    // ── 6. Optional success callback ──────────────────────────────\n    if (user && onAuthSuccess) {\n      await onAuthSuccess({ id: user.id, email: user.email ?? undefined });\n    }\n\n    return response;\n  };\n}\n","import { createServerClient, type CookieOptions } from \"@supabase/ssr\";\nimport { cookies } from \"next/headers\";\nimport type { SupabaseClient } from \"@supabase/supabase-js\";\n\nimport type { ActionResponse, SupaError } from \"../../types\";\nimport { handleSupaError } from \"../../shared/utils/error-handler\";\n\n/**\n * Create a type-safe Server Action that automatically:\n * 1. Initialises a Supabase server client (with cookies)\n * 2. Wraps execution in try/catch\n * 3. Returns a standardised `{ data, error }` response\n *\n * @example\n * ```ts\n * // app/actions/profile.ts\n * \"use server\";\n * import { createAction } from \"next-supa-utils/server\";\n *\n * export const getProfile = createAction(async (supabase, userId: string) => {\n *   const { data, error } = await supabase\n *     .from(\"profiles\")\n *     .select(\"*\")\n *     .eq(\"id\", userId)\n *     .single();\n *\n *   if (error) throw error;\n *   return data;\n * });\n *\n * // Usage in a Server Component or Client Component:\n * const result = await getProfile(\"user-uuid\");\n * if (result.error) { ... }\n * ```\n */\nexport function createAction<TArgs extends unknown[], TResult>(\n  fn: (supabase: SupabaseClient, ...args: TArgs) => Promise<TResult>,\n): (...args: TArgs) => Promise<ActionResponse<TResult>> {\n  return async (...args: TArgs): Promise<ActionResponse<TResult>> => {\n    try {\n      const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;\n      const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;\n\n      if (!supabaseUrl || !supabaseAnonKey) {\n        return {\n          data: null,\n          error: {\n            message:\n              \"Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.\",\n            code: \"CONFIG_ERROR\",\n          },\n        };\n      }\n\n      const cookieStore = await cookies();\n\n      const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n        cookies: {\n          getAll() {\n            return cookieStore.getAll();\n          },\n          setAll(cookiesToSet: { name: string; value: string; options?: CookieOptions }[]) {\n            try {\n              cookiesToSet.forEach(({ name, value, options }) => {\n                cookieStore.set(name, value, options);\n              });\n            } catch {\n              // `cookies().set()` throws when called from a Server Component.\n              // In that context we only need read access — the middleware\n              // handles token refresh.\n            }\n          },\n        },\n      });\n\n      const data = await fn(supabase, ...args);\n\n      return { data, error: null };\n    } catch (caught: unknown) {\n      const error: SupaError = handleSupaError(caught);\n      return { data: null, error };\n    }\n  };\n}\n","import type { SupaError } from \"../../types\";\n\n/**\n * Normalize any thrown value into a consistent `SupaError` shape.\n *\n * Handles:\n * - Supabase `AuthError` / `PostgrestError` (has `.message` and optional `.code` / `.status`)\n * - Standard `Error` instances\n * - Plain strings\n * - Unknown values (fallback)\n */\nexport function handleSupaError(error: unknown): SupaError {\n  // ── Supabase errors & standard Error instances ──────────────────\n  if (error instanceof Error) {\n    const record = error as unknown as Record<string, unknown>;\n    return {\n      message: error.message,\n      code: typeof record.code === \"string\" ? record.code : undefined,\n      status: typeof record.status === \"number\" ? record.status : undefined,\n    };\n  }\n\n  // ── Plain object with a message property ────────────────────────\n  if (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"message\" in error &&\n    typeof (error as Record<string, unknown>).message === \"string\"\n  ) {\n    const err = error as Record<string, unknown>;\n    return {\n      message: err.message as string,\n      code: typeof err.code === \"string\" ? err.code : undefined,\n      status: typeof err.status === \"number\" ? err.status : undefined,\n    };\n  }\n\n  // ── String ──────────────────────────────────────────────────────\n  if (typeof error === \"string\") {\n    return { message: error };\n  }\n\n  // ── Fallback ────────────────────────────────────────────────────\n  return { message: \"An unknown error occurred\" };\n}\n"],"mappings":"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","names":["import_ssr"]}
+{"version":3,"sources":["../../src/server/index.ts","../../src/server/middleware/withSupaAuth.ts","../../src/server/actions/actionWrapper.ts","../../src/shared/utils/error-handler.ts"],"sourcesContent":["// ── Server entry point ──────────────────────────────────────────────\n// This module should ONLY be imported in server-side contexts:\n// middleware.ts, Server Components, Server Actions, Route Handlers.\n\nexport { withSupaAuth } from \"./middleware/withSupaAuth\";\nexport { createAction } from \"./actions/actionWrapper\";\n\n// Re-export types consumers commonly need alongside server helpers.\nexport type { MiddlewareOptions, RouteConfig, ActionResponse, SupaError } from \"../types\";\n","import { createServerClient, type CookieOptions } from \"@supabase/ssr\";\nimport { NextResponse, type NextRequest } from \"next/server\";\n\nimport type { MiddlewareOptions, RouteConfig } from \"../../types\";\n\n// ── Path matching utility ───────────────────────────────────────────\n\n/**\n * Converts a route pattern into a RegExp for matching.\n *\n * Supports:\n * - Exact:    `\"/settings\"`       → matches only `/settings`\n * - Prefix:   `\"/dashboard\"`      → matches `/dashboard`, `/dashboard/stats`\n * - Wildcard: `\"/admin/:path*\"`   → matches `/admin`, `/admin/users`, `/admin/a/b/c`\n */\nfunction matchPath(pattern: string, pathname: string): boolean {\n  // Wildcard pattern: \"/admin/:path*\" → match \"/admin\" and everything below\n  if (pattern.includes(\":path*\")) {\n    const prefix = pattern.replace(/:path\\*$/, \"\").replace(/\\/$/, \"\");\n    return pathname === prefix || pathname.startsWith(prefix + \"/\");\n  }\n\n  // Prefix matching: \"/dashboard\" matches \"/dashboard/anything\"\n  return pathname === pattern || pathname.startsWith(pattern + \"/\");\n}\n\n/**\n * Finds the first `RouteConfig` whose pattern matches `pathname`, or `undefined`.\n */\nfunction findMatchingRoute(\n  routes: RouteConfig[],\n  pathname: string,\n): RouteConfig | undefined {\n  return routes.find((route) => matchPath(route.path, pathname));\n}\n\n// ── Role extraction utility ─────────────────────────────────────────\n\ntype UserMeta = {\n  user_metadata: Record<string, unknown>;\n  app_metadata: Record<string, unknown>;\n};\n\nfunction extractRole(\n  user: UserMeta,\n  extractor: MiddlewareOptions[\"roleExtractor\"],\n): string | string[] | undefined {\n  if (typeof extractor === \"function\") {\n    return extractor(user);\n  }\n\n  const source =\n    extractor === \"app_metadata\" ? user.app_metadata : user.user_metadata;\n\n  const raw = source?.role;\n\n  if (typeof raw === \"string\") return raw;\n  if (Array.isArray(raw) && raw.every((r) => typeof r === \"string\")) {\n    return raw as string[];\n  }\n\n  return undefined;\n}\n\n/**\n * Check whether the user's role(s) satisfy the route's `allowedRoles`.\n */\nfunction hasRequiredRole(\n  userRole: string | string[] | undefined,\n  allowedRoles: string[] | undefined,\n): boolean {\n  // No role restriction → any authenticated user is allowed.\n  if (!allowedRoles || allowedRoles.length === 0) return true;\n\n  if (!userRole) return false;\n\n  const roles = Array.isArray(userRole) ? userRole : [userRole];\n  return roles.some((r) => allowedRoles.includes(r));\n}\n\n// ── Main middleware factory ─────────────────────────────────────────\n\n/**\n * Create a Next.js middleware handler that protects routes with\n * authentication **and** optional role-based access control (RBAC).\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { withSupaAuth } from \"next-supa-utils/server\";\n *\n * export default withSupaAuth({\n *   routes: [\n *     { path: \"/dashboard\" },                                    // any authed user\n *     { path: \"/admin/:path*\", allowedRoles: [\"admin\"] },        // admin only\n *     { path: \"/editor/:path*\", allowedRoles: [\"admin\", \"editor\"] },\n *   ],\n *   redirectTo: \"/login\",\n *   roleExtractor: \"user_metadata\", // or \"app_metadata\" or a custom fn\n * });\n *\n * export const config = {\n *   matcher: [\"/((?!_next/static|_next/image|favicon.ico|.*\\\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)\"],\n * };\n * ```\n */\nexport function withSupaAuth(options: MiddlewareOptions) {\n  const {\n    routes,\n    redirectTo = \"/login\",\n    roleExtractor = \"user_metadata\",\n    onAuthSuccess,\n  } = options;\n\n  return async function middleware(request: NextRequest): Promise<NextResponse> {\n    // ── 1. Create a mutable response so Supabase can set cookies ──\n    let response = NextResponse.next({\n      request: { headers: request.headers },\n    });\n\n    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;\n    const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;\n\n    if (!supabaseUrl || !supabaseAnonKey) {\n      console.error(\n        \"[next-supa-utils] Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.\",\n      );\n      return response;\n    }\n\n    // ── 2. Initialize server client with middleware cookie helpers ─\n    const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n      cookies: {\n        getAll() {\n          return request.cookies.getAll();\n        },\n        setAll(cookiesToSet: { name: string; value: string; options?: CookieOptions }[]) {\n          cookiesToSet.forEach(({ name, value }) => {\n            request.cookies.set(name, value);\n          });\n\n          response = NextResponse.next({ request });\n\n          cookiesToSet.forEach(({ name, value, options }) => {\n            response.cookies.set(name, value, options);\n          });\n        },\n      },\n    });\n\n    // ── 3. Refresh session (required to keep tokens alive) ────────\n    const {\n      data: { user },\n    } = await supabase.auth.getUser();\n\n    const { pathname } = request.nextUrl;\n\n    // ── 4. Find the matching route config ─────────────────────────\n    const matchedRoute = findMatchingRoute(routes, pathname);\n\n    // No matching route → not a protected path, pass through.\n    if (!matchedRoute) {\n      return response;\n    }\n\n    // ── 5. Check authentication ───────────────────────────────────\n    if (!user) {\n      const loginUrl = new URL(redirectTo, request.url);\n      loginUrl.searchParams.set(\"next\", pathname);\n      return NextResponse.redirect(loginUrl);\n    }\n\n    // ── 6. Check role-based access ────────────────────────────────\n    const userRole = extractRole(user, roleExtractor);\n\n    if (!hasRequiredRole(userRole, matchedRoute.allowedRoles)) {\n      // User is logged in but lacks the required role.\n      const forbiddenUrl = new URL(redirectTo, request.url);\n      forbiddenUrl.searchParams.set(\"error\", \"forbidden\");\n      forbiddenUrl.searchParams.set(\"next\", pathname);\n      return NextResponse.redirect(forbiddenUrl);\n    }\n\n    // ── 7. Success callback ───────────────────────────────────────\n    if (onAuthSuccess) {\n      await onAuthSuccess({\n        id: user.id,\n        email: user.email ?? undefined,\n        role: userRole,\n      });\n    }\n\n    return response;\n  };\n}\n","import { createServerClient, type CookieOptions } from \"@supabase/ssr\";\nimport { cookies } from \"next/headers\";\nimport type { SupabaseClient } from \"@supabase/supabase-js\";\n\nimport type { ActionResponse, SupaError } from \"../../types\";\nimport { handleSupaError } from \"../../shared/utils/error-handler\";\n\n/**\n * Create a type-safe Server Action that automatically:\n * 1. Initialises a Supabase server client (with cookies)\n * 2. Wraps execution in try/catch\n * 3. Returns a standardised `{ data, error }` response\n *\n * @example\n * ```ts\n * // app/actions/profile.ts\n * \"use server\";\n * import { createAction } from \"next-supa-utils/server\";\n *\n * export const getProfile = createAction(async (supabase, userId: string) => {\n *   const { data, error } = await supabase\n *     .from(\"profiles\")\n *     .select(\"*\")\n *     .eq(\"id\", userId)\n *     .single();\n *\n *   if (error) throw error;\n *   return data;\n * });\n *\n * // Usage in a Server Component or Client Component:\n * const result = await getProfile(\"user-uuid\");\n * if (result.error) { ... }\n * ```\n */\nexport function createAction<TArgs extends unknown[], TResult>(\n  fn: (supabase: SupabaseClient, ...args: TArgs) => Promise<TResult>,\n): (...args: TArgs) => Promise<ActionResponse<TResult>> {\n  return async (...args: TArgs): Promise<ActionResponse<TResult>> => {\n    try {\n      const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;\n      const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;\n\n      if (!supabaseUrl || !supabaseAnonKey) {\n        return {\n          data: null,\n          error: {\n            message:\n              \"Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.\",\n            code: \"CONFIG_ERROR\",\n          },\n        };\n      }\n\n      const cookieStore = await cookies();\n\n      const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n        cookies: {\n          getAll() {\n            return cookieStore.getAll();\n          },\n          setAll(cookiesToSet: { name: string; value: string; options?: CookieOptions }[]) {\n            try {\n              cookiesToSet.forEach(({ name, value, options }) => {\n                cookieStore.set(name, value, options);\n              });\n            } catch {\n              // `cookies().set()` throws when called from a Server Component.\n              // In that context we only need read access — the middleware\n              // handles token refresh.\n            }\n          },\n        },\n      });\n\n      const data = await fn(supabase, ...args);\n\n      return { data, error: null };\n    } catch (caught: unknown) {\n      const error: SupaError = handleSupaError(caught);\n      return { data: null, error };\n    }\n  };\n}\n","import type { SupaError } from \"../../types\";\n\n/**\n * Normalize any thrown value into a consistent `SupaError` shape.\n *\n * Handles:\n * - Supabase `AuthError` / `PostgrestError` (has `.message` and optional `.code` / `.status`)\n * - Standard `Error` instances\n * - Plain strings\n * - Unknown values (fallback)\n */\nexport function handleSupaError(error: unknown): SupaError {\n  // ── Supabase errors & standard Error instances ──────────────────\n  if (error instanceof Error) {\n    const record = error as unknown as Record<string, unknown>;\n    return {\n      message: error.message,\n      code: typeof record.code === \"string\" ? record.code : undefined,\n      status: typeof record.status === \"number\" ? record.status : undefined,\n    };\n  }\n\n  // ── Plain object with a message property ────────────────────────\n  if (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"message\" in error &&\n    typeof (error as Record<string, unknown>).message === \"string\"\n  ) {\n    const err = error as Record<string, unknown>;\n    return {\n      message: err.message as string,\n      code: typeof err.code === \"string\" ? err.code : undefined,\n      status: typeof err.status === \"number\" ? err.status : undefined,\n    };\n  }\n\n  // ── String ──────────────────────────────────────────────────────\n  if (typeof error === \"string\") {\n    return { message: error };\n  }\n\n  // ── Fallback ────────────────────────────────────────────────────\n  return { message: \"An unknown error occurred\" };\n}\n"],"mappings":"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","names":["options","import_ssr"]}

package/dist/server/index.d.cts

@@ -15,38 +15,75 @@ type ActionResponse<T> = {
     data: null;
     error: SupaError;
 };
-interface SupaAuthConfig {
+/**
+ * Defines a protected route with optional role-based access control.
+ *
+ * @example
+ * ```ts
+ * { path: "/admin/:path*", allowedRoles: ["admin", "super_admin"] }
+ * ```
+ */
+interface RouteConfig {
+    /**
+     * Route pattern to match.
+     *
+     * Supports:
+     * - Exact paths: `"/settings"`
+     * - Prefix matching: `"/dashboard"` matches `/dashboard/anything`
+     * - Wildcards: `"/admin/:path*"` matches `/admin/users`, `/admin/settings/edit`, etc.
+     */
+    path: string;
     /**
-     * Route prefixes that require an authenticated user.
-     * Supports simple prefix matching.
+     * Roles that are allowed to access this route.
+     *
+     * - If **omitted or empty**, any *authenticated* user can access the route.
+     * - If **provided**, only users whose role is in this list are allowed.
      *
-     * @example ["/dashboard", "/admin", "/settings"]
+     * @example ["admin", "editor"]
+     */
+    allowedRoles?: string[];
+}
+/**
+ * Configuration for the `withSupaAuth` middleware.
+ */
+interface MiddlewareOptions {
+    /**
+     * Protected route definitions. Each entry can optionally restrict access
+     * to specific roles via `allowedRoles`.
      */
-    protectedRoutes: string[];
+    routes: RouteConfig[];
     /**
-     * Where to redirect unauthenticated users.
+     * Where to redirect unauthenticated or unauthorized users.
      * @default "/login"
      */
     redirectTo?: string;
     /**
-     * Routes that are always public, even if they match a protected prefix.
+     * Strategy for extracting the user's role from the Supabase user object.
+     *
+     * - `"user_metadata"` — reads `user.user_metadata.role`
+     * - `"app_metadata"` — reads `user.app_metadata.role`
+     * - A custom function for advanced scenarios (e.g. multiple roles, JWT claims).
      *
-     * @example ["/admin/login"]
+     * @default "user_metadata"
      */
-    publicRoutes?: string[];
+    roleExtractor?: "user_metadata" | "app_metadata" | ((user: {
+        user_metadata: Record<string, unknown>;
+        app_metadata: Record<string, unknown>;
+    }) => string | string[] | undefined);
     /**
-     * Optional callback invoked after session refresh,
-     * before the redirect decision. Useful for custom logging or headers.
+     * Optional callback invoked when a user is authenticated and authorized.
+     * Useful for logging, analytics, or injecting custom response headers.
      */
     onAuthSuccess?: (user: {
         id: string;
         email?: string;
+        role?: string | string[];
     }) => void | Promise<void>;
 }
 
 /**
- * Create a Next.js middleware handler that protects routes based on
- * Supabase authentication state.
+ * Create a Next.js middleware handler that protects routes with
+ * authentication **and** optional role-based access control (RBAC).
  *
  * @example
  * ```ts
@@ -54,9 +91,13 @@ interface SupaAuthConfig {
  * import { withSupaAuth } from "next-supa-utils/server";
  *
  * export default withSupaAuth({
- *   protectedRoutes: ["/dashboard", "/admin"],
+ *   routes: [
+ *     { path: "/dashboard" },                                    // any authed user
+ *     { path: "/admin/:path*", allowedRoles: ["admin"] },        // admin only
+ *     { path: "/editor/:path*", allowedRoles: ["admin", "editor"] },
+ *   ],
  *   redirectTo: "/login",
- *   publicRoutes: ["/admin/login"],
+ *   roleExtractor: "user_metadata", // or "app_metadata" or a custom fn
  * });
  *
  * export const config = {
@@ -64,7 +105,7 @@ interface SupaAuthConfig {
  * };
  * ```
  */
-declare function withSupaAuth(config: SupaAuthConfig): (request: NextRequest) => Promise<NextResponse>;
+declare function withSupaAuth(options: MiddlewareOptions): (request: NextRequest) => Promise<NextResponse>;
 
 /**
  * Create a type-safe Server Action that automatically:
@@ -96,4 +137,4 @@ declare function withSupaAuth(config: SupaAuthConfig): (request: NextRequest) =>
  */
 declare function createAction<TArgs extends unknown[], TResult>(fn: (supabase: SupabaseClient, ...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<ActionResponse<TResult>>;
 
-export { type ActionResponse, type SupaAuthConfig, type SupaError, createAction, withSupaAuth };
+export { type ActionResponse, type MiddlewareOptions, type RouteConfig, type SupaError, createAction, withSupaAuth };

package/dist/server/index.d.ts

@@ -15,38 +15,75 @@ type ActionResponse<T> = {
     data: null;
     error: SupaError;
 };
-interface SupaAuthConfig {
+/**
+ * Defines a protected route with optional role-based access control.
+ *
+ * @example
+ * ```ts
+ * { path: "/admin/:path*", allowedRoles: ["admin", "super_admin"] }
+ * ```
+ */
+interface RouteConfig {
+    /**
+     * Route pattern to match.
+     *
+     * Supports:
+     * - Exact paths: `"/settings"`
+     * - Prefix matching: `"/dashboard"` matches `/dashboard/anything`
+     * - Wildcards: `"/admin/:path*"` matches `/admin/users`, `/admin/settings/edit`, etc.
+     */
+    path: string;
     /**
-     * Route prefixes that require an authenticated user.
-     * Supports simple prefix matching.
+     * Roles that are allowed to access this route.
+     *
+     * - If **omitted or empty**, any *authenticated* user can access the route.
+     * - If **provided**, only users whose role is in this list are allowed.
      *
-     * @example ["/dashboard", "/admin", "/settings"]
+     * @example ["admin", "editor"]
+     */
+    allowedRoles?: string[];
+}
+/**
+ * Configuration for the `withSupaAuth` middleware.
+ */
+interface MiddlewareOptions {
+    /**
+     * Protected route definitions. Each entry can optionally restrict access
+     * to specific roles via `allowedRoles`.
      */
-    protectedRoutes: string[];
+    routes: RouteConfig[];
     /**
-     * Where to redirect unauthenticated users.
+     * Where to redirect unauthenticated or unauthorized users.
      * @default "/login"
      */
     redirectTo?: string;
     /**
-     * Routes that are always public, even if they match a protected prefix.
+     * Strategy for extracting the user's role from the Supabase user object.
+     *
+     * - `"user_metadata"` — reads `user.user_metadata.role`
+     * - `"app_metadata"` — reads `user.app_metadata.role`
+     * - A custom function for advanced scenarios (e.g. multiple roles, JWT claims).
      *
-     * @example ["/admin/login"]
+     * @default "user_metadata"
      */
-    publicRoutes?: string[];
+    roleExtractor?: "user_metadata" | "app_metadata" | ((user: {
+        user_metadata: Record<string, unknown>;
+        app_metadata: Record<string, unknown>;
+    }) => string | string[] | undefined);
     /**
-     * Optional callback invoked after session refresh,
-     * before the redirect decision. Useful for custom logging or headers.
+     * Optional callback invoked when a user is authenticated and authorized.
+     * Useful for logging, analytics, or injecting custom response headers.
      */
     onAuthSuccess?: (user: {
         id: string;
         email?: string;
+        role?: string | string[];
     }) => void | Promise<void>;
 }
 
 /**
- * Create a Next.js middleware handler that protects routes based on
- * Supabase authentication state.
+ * Create a Next.js middleware handler that protects routes with
+ * authentication **and** optional role-based access control (RBAC).
  *
  * @example
  * ```ts
@@ -54,9 +91,13 @@ interface SupaAuthConfig {
  * import { withSupaAuth } from "next-supa-utils/server";
  *
  * export default withSupaAuth({
- *   protectedRoutes: ["/dashboard", "/admin"],
+ *   routes: [
+ *     { path: "/dashboard" },                                    // any authed user
+ *     { path: "/admin/:path*", allowedRoles: ["admin"] },        // admin only
+ *     { path: "/editor/:path*", allowedRoles: ["admin", "editor"] },
+ *   ],
  *   redirectTo: "/login",
- *   publicRoutes: ["/admin/login"],
+ *   roleExtractor: "user_metadata", // or "app_metadata" or a custom fn
  * });
  *
  * export const config = {
@@ -64,7 +105,7 @@ interface SupaAuthConfig {
  * };
  * ```
  */
-declare function withSupaAuth(config: SupaAuthConfig): (request: NextRequest) => Promise<NextResponse>;
+declare function withSupaAuth(options: MiddlewareOptions): (request: NextRequest) => Promise<NextResponse>;
 
 /**
  * Create a type-safe Server Action that automatically:
@@ -96,4 +137,4 @@ declare function withSupaAuth(config: SupaAuthConfig): (request: NextRequest) =>
  */
 declare function createAction<TArgs extends unknown[], TResult>(fn: (supabase: SupabaseClient, ...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<ActionResponse<TResult>>;
 
-export { type ActionResponse, type SupaAuthConfig, type SupaError, createAction, withSupaAuth };
+export { type ActionResponse, type MiddlewareOptions, type RouteConfig, type SupaError, createAction, withSupaAuth };

package/dist/server/index.js

@@ -1,13 +1,41 @@
 // src/server/middleware/withSupaAuth.ts
 import { createServerClient } from "@supabase/ssr";
 import { NextResponse } from "next/server";
-function withSupaAuth(config) {
+function matchPath(pattern, pathname) {
+  if (pattern.includes(":path*")) {
+    const prefix = pattern.replace(/:path\*$/, "").replace(/\/$/, "");
+    return pathname === prefix || pathname.startsWith(prefix + "/");
+  }
+  return pathname === pattern || pathname.startsWith(pattern + "/");
+}
+function findMatchingRoute(routes, pathname) {
+  return routes.find((route) => matchPath(route.path, pathname));
+}
+function extractRole(user, extractor) {
+  if (typeof extractor === "function") {
+    return extractor(user);
+  }
+  const source = extractor === "app_metadata" ? user.app_metadata : user.user_metadata;
+  const raw = source?.role;
+  if (typeof raw === "string") return raw;
+  if (Array.isArray(raw) && raw.every((r) => typeof r === "string")) {
+    return raw;
+  }
+  return void 0;
+}
+function hasRequiredRole(userRole, allowedRoles) {
+  if (!allowedRoles || allowedRoles.length === 0) return true;
+  if (!userRole) return false;
+  const roles = Array.isArray(userRole) ? userRole : [userRole];
+  return roles.some((r) => allowedRoles.includes(r));
+}
+function withSupaAuth(options) {
   const {
-    protectedRoutes,
+    routes,
     redirectTo = "/login",
-    publicRoutes = [],
+    roleExtractor = "user_metadata",
     onAuthSuccess
-  } = config;
+  } = options;
   return async function middleware(request) {
     let response = NextResponse.next({
       request: { headers: request.headers }
@@ -30,8 +58,8 @@ function withSupaAuth(config) {
             request.cookies.set(name, value);
           });
           response = NextResponse.next({ request });
-          cookiesToSet.forEach(({ name, value, options }) => {
-            response.cookies.set(name, value, options);
+          cookiesToSet.forEach(({ name, value, options: options2 }) => {
+            response.cookies.set(name, value, options2);
           });
         }
       }
@@ -40,22 +68,28 @@ function withSupaAuth(config) {
       data: { user }
     } = await supabase.auth.getUser();
     const { pathname } = request.nextUrl;
-    const isPublicRoute = publicRoutes.some(
-      (route) => pathname.startsWith(route)
-    );
-    if (isPublicRoute) {
+    const matchedRoute = findMatchingRoute(routes, pathname);
+    if (!matchedRoute) {
       return response;
     }
-    const isProtectedRoute = protectedRoutes.some(
-      (route) => pathname.startsWith(route)
-    );
-    if (isProtectedRoute && !user) {
+    if (!user) {
       const loginUrl = new URL(redirectTo, request.url);
       loginUrl.searchParams.set("next", pathname);
       return NextResponse.redirect(loginUrl);
     }
-    if (user && onAuthSuccess) {
-      await onAuthSuccess({ id: user.id, email: user.email ?? void 0 });
+    const userRole = extractRole(user, roleExtractor);
+    if (!hasRequiredRole(userRole, matchedRoute.allowedRoles)) {
+      const forbiddenUrl = new URL(redirectTo, request.url);
+      forbiddenUrl.searchParams.set("error", "forbidden");
+      forbiddenUrl.searchParams.set("next", pathname);
+      return NextResponse.redirect(forbiddenUrl);
+    }
+    if (onAuthSuccess) {
+      await onAuthSuccess({
+        id: user.id,
+        email: user.email ?? void 0,
+        role: userRole
+      });
     }
     return response;
   };

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/server/middleware/withSupaAuth.ts","../../src/server/actions/actionWrapper.ts","../../src/shared/utils/error-handler.ts"],"sourcesContent":["import { createServerClient, type CookieOptions } from \"@supabase/ssr\";\nimport { NextResponse, type NextRequest } from \"next/server\";\n\nimport type { SupaAuthConfig } from \"../../types\";\n\n/**\n * Create a Next.js middleware handler that protects routes based on\n * Supabase authentication state.\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { withSupaAuth } from \"next-supa-utils/server\";\n *\n * export default withSupaAuth({\n *   protectedRoutes: [\"/dashboard\", \"/admin\"],\n *   redirectTo: \"/login\",\n *   publicRoutes: [\"/admin/login\"],\n * });\n *\n * export const config = {\n *   matcher: [\"/((?!_next/static|_next/image|favicon.ico|.*\\\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)\"],\n * };\n * ```\n */\nexport function withSupaAuth(config: SupaAuthConfig) {\n  const {\n    protectedRoutes,\n    redirectTo = \"/login\",\n    publicRoutes = [],\n    onAuthSuccess,\n  } = config;\n\n  return async function middleware(request: NextRequest): Promise<NextResponse> {\n    // ── 1. Create a mutable response so Supabase can set cookies ──\n    let response = NextResponse.next({\n      request: { headers: request.headers },\n    });\n\n    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;\n    const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;\n\n    if (!supabaseUrl || !supabaseAnonKey) {\n      console.error(\n        \"[next-supa-utils] Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.\",\n      );\n      return response;\n    }\n\n    // ── 2. Initialize server client with middleware cookie helpers ─\n    const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n      cookies: {\n        getAll() {\n          return request.cookies.getAll();\n        },\n        setAll(cookiesToSet: { name: string; value: string; options?: CookieOptions }[]) {\n          // Forward cookies to the request so downstream server\n          // components can read the updated session.\n          cookiesToSet.forEach(({ name, value }) => {\n            request.cookies.set(name, value);\n          });\n\n          // Re-create the response so it carries the updated request.\n          response = NextResponse.next({ request });\n\n          // Set cookies on the outgoing response so the browser\n          // stores the refreshed tokens.\n          cookiesToSet.forEach(({ name, value, options }) => {\n            response.cookies.set(name, value, options);\n          });\n        },\n      },\n    });\n\n    // ── 3. Refresh session (required to keep tokens alive) ────────\n    const {\n      data: { user },\n    } = await supabase.auth.getUser();\n\n    const { pathname } = request.nextUrl;\n\n    // ── 4. Check if current path matches a public override ────────\n    const isPublicRoute = publicRoutes.some((route) =>\n      pathname.startsWith(route),\n    );\n\n    if (isPublicRoute) {\n      return response;\n    }\n\n    // ── 5. Check if current path requires authentication ──────────\n    const isProtectedRoute = protectedRoutes.some((route) =>\n      pathname.startsWith(route),\n    );\n\n    if (isProtectedRoute && !user) {\n      const loginUrl = new URL(redirectTo, request.url);\n      // Preserve the originally-requested URL so the app can redirect\n      // back after login.\n      loginUrl.searchParams.set(\"next\", pathname);\n      return NextResponse.redirect(loginUrl);\n    }\n\n    // ── 6. Optional success callback ──────────────────────────────\n    if (user && onAuthSuccess) {\n      await onAuthSuccess({ id: user.id, email: user.email ?? undefined });\n    }\n\n    return response;\n  };\n}\n","import { createServerClient, type CookieOptions } from \"@supabase/ssr\";\nimport { cookies } from \"next/headers\";\nimport type { SupabaseClient } from \"@supabase/supabase-js\";\n\nimport type { ActionResponse, SupaError } from \"../../types\";\nimport { handleSupaError } from \"../../shared/utils/error-handler\";\n\n/**\n * Create a type-safe Server Action that automatically:\n * 1. Initialises a Supabase server client (with cookies)\n * 2. Wraps execution in try/catch\n * 3. Returns a standardised `{ data, error }` response\n *\n * @example\n * ```ts\n * // app/actions/profile.ts\n * \"use server\";\n * import { createAction } from \"next-supa-utils/server\";\n *\n * export const getProfile = createAction(async (supabase, userId: string) => {\n *   const { data, error } = await supabase\n *     .from(\"profiles\")\n *     .select(\"*\")\n *     .eq(\"id\", userId)\n *     .single();\n *\n *   if (error) throw error;\n *   return data;\n * });\n *\n * // Usage in a Server Component or Client Component:\n * const result = await getProfile(\"user-uuid\");\n * if (result.error) { ... }\n * ```\n */\nexport function createAction<TArgs extends unknown[], TResult>(\n  fn: (supabase: SupabaseClient, ...args: TArgs) => Promise<TResult>,\n): (...args: TArgs) => Promise<ActionResponse<TResult>> {\n  return async (...args: TArgs): Promise<ActionResponse<TResult>> => {\n    try {\n      const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;\n      const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;\n\n      if (!supabaseUrl || !supabaseAnonKey) {\n        return {\n          data: null,\n          error: {\n            message:\n              \"Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.\",\n            code: \"CONFIG_ERROR\",\n          },\n        };\n      }\n\n      const cookieStore = await cookies();\n\n      const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n        cookies: {\n          getAll() {\n            return cookieStore.getAll();\n          },\n          setAll(cookiesToSet: { name: string; value: string; options?: CookieOptions }[]) {\n            try {\n              cookiesToSet.forEach(({ name, value, options }) => {\n                cookieStore.set(name, value, options);\n              });\n            } catch {\n              // `cookies().set()` throws when called from a Server Component.\n              // In that context we only need read access — the middleware\n              // handles token refresh.\n            }\n          },\n        },\n      });\n\n      const data = await fn(supabase, ...args);\n\n      return { data, error: null };\n    } catch (caught: unknown) {\n      const error: SupaError = handleSupaError(caught);\n      return { data: null, error };\n    }\n  };\n}\n","import type { SupaError } from \"../../types\";\n\n/**\n * Normalize any thrown value into a consistent `SupaError` shape.\n *\n * Handles:\n * - Supabase `AuthError` / `PostgrestError` (has `.message` and optional `.code` / `.status`)\n * - Standard `Error` instances\n * - Plain strings\n * - Unknown values (fallback)\n */\nexport function handleSupaError(error: unknown): SupaError {\n  // ── Supabase errors & standard Error instances ──────────────────\n  if (error instanceof Error) {\n    const record = error as unknown as Record<string, unknown>;\n    return {\n      message: error.message,\n      code: typeof record.code === \"string\" ? record.code : undefined,\n      status: typeof record.status === \"number\" ? record.status : undefined,\n    };\n  }\n\n  // ── Plain object with a message property ────────────────────────\n  if (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"message\" in error &&\n    typeof (error as Record<string, unknown>).message === \"string\"\n  ) {\n    const err = error as Record<string, unknown>;\n    return {\n      message: err.message as string,\n      code: typeof err.code === \"string\" ? err.code : undefined,\n      status: typeof err.status === \"number\" ? err.status : undefined,\n    };\n  }\n\n  // ── String ──────────────────────────────────────────────────────\n  if (typeof error === \"string\") {\n    return { message: error };\n  }\n\n  // ── Fallback ────────────────────────────────────────────────────\n  return { message: \"An unknown error occurred\" };\n}\n"],"mappings":"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","names":["createServerClient","createServerClient"]}
+{"version":3,"sources":["../../src/server/middleware/withSupaAuth.ts","../../src/server/actions/actionWrapper.ts","../../src/shared/utils/error-handler.ts"],"sourcesContent":["import { createServerClient, type CookieOptions } from \"@supabase/ssr\";\nimport { NextResponse, type NextRequest } from \"next/server\";\n\nimport type { MiddlewareOptions, RouteConfig } from \"../../types\";\n\n// ── Path matching utility ───────────────────────────────────────────\n\n/**\n * Converts a route pattern into a RegExp for matching.\n *\n * Supports:\n * - Exact:    `\"/settings\"`       → matches only `/settings`\n * - Prefix:   `\"/dashboard\"`      → matches `/dashboard`, `/dashboard/stats`\n * - Wildcard: `\"/admin/:path*\"`   → matches `/admin`, `/admin/users`, `/admin/a/b/c`\n */\nfunction matchPath(pattern: string, pathname: string): boolean {\n  // Wildcard pattern: \"/admin/:path*\" → match \"/admin\" and everything below\n  if (pattern.includes(\":path*\")) {\n    const prefix = pattern.replace(/:path\\*$/, \"\").replace(/\\/$/, \"\");\n    return pathname === prefix || pathname.startsWith(prefix + \"/\");\n  }\n\n  // Prefix matching: \"/dashboard\" matches \"/dashboard/anything\"\n  return pathname === pattern || pathname.startsWith(pattern + \"/\");\n}\n\n/**\n * Finds the first `RouteConfig` whose pattern matches `pathname`, or `undefined`.\n */\nfunction findMatchingRoute(\n  routes: RouteConfig[],\n  pathname: string,\n): RouteConfig | undefined {\n  return routes.find((route) => matchPath(route.path, pathname));\n}\n\n// ── Role extraction utility ─────────────────────────────────────────\n\ntype UserMeta = {\n  user_metadata: Record<string, unknown>;\n  app_metadata: Record<string, unknown>;\n};\n\nfunction extractRole(\n  user: UserMeta,\n  extractor: MiddlewareOptions[\"roleExtractor\"],\n): string | string[] | undefined {\n  if (typeof extractor === \"function\") {\n    return extractor(user);\n  }\n\n  const source =\n    extractor === \"app_metadata\" ? user.app_metadata : user.user_metadata;\n\n  const raw = source?.role;\n\n  if (typeof raw === \"string\") return raw;\n  if (Array.isArray(raw) && raw.every((r) => typeof r === \"string\")) {\n    return raw as string[];\n  }\n\n  return undefined;\n}\n\n/**\n * Check whether the user's role(s) satisfy the route's `allowedRoles`.\n */\nfunction hasRequiredRole(\n  userRole: string | string[] | undefined,\n  allowedRoles: string[] | undefined,\n): boolean {\n  // No role restriction → any authenticated user is allowed.\n  if (!allowedRoles || allowedRoles.length === 0) return true;\n\n  if (!userRole) return false;\n\n  const roles = Array.isArray(userRole) ? userRole : [userRole];\n  return roles.some((r) => allowedRoles.includes(r));\n}\n\n// ── Main middleware factory ─────────────────────────────────────────\n\n/**\n * Create a Next.js middleware handler that protects routes with\n * authentication **and** optional role-based access control (RBAC).\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { withSupaAuth } from \"next-supa-utils/server\";\n *\n * export default withSupaAuth({\n *   routes: [\n *     { path: \"/dashboard\" },                                    // any authed user\n *     { path: \"/admin/:path*\", allowedRoles: [\"admin\"] },        // admin only\n *     { path: \"/editor/:path*\", allowedRoles: [\"admin\", \"editor\"] },\n *   ],\n *   redirectTo: \"/login\",\n *   roleExtractor: \"user_metadata\", // or \"app_metadata\" or a custom fn\n * });\n *\n * export const config = {\n *   matcher: [\"/((?!_next/static|_next/image|favicon.ico|.*\\\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)\"],\n * };\n * ```\n */\nexport function withSupaAuth(options: MiddlewareOptions) {\n  const {\n    routes,\n    redirectTo = \"/login\",\n    roleExtractor = \"user_metadata\",\n    onAuthSuccess,\n  } = options;\n\n  return async function middleware(request: NextRequest): Promise<NextResponse> {\n    // ── 1. Create a mutable response so Supabase can set cookies ──\n    let response = NextResponse.next({\n      request: { headers: request.headers },\n    });\n\n    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;\n    const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;\n\n    if (!supabaseUrl || !supabaseAnonKey) {\n      console.error(\n        \"[next-supa-utils] Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.\",\n      );\n      return response;\n    }\n\n    // ── 2. Initialize server client with middleware cookie helpers ─\n    const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n      cookies: {\n        getAll() {\n          return request.cookies.getAll();\n        },\n        setAll(cookiesToSet: { name: string; value: string; options?: CookieOptions }[]) {\n          cookiesToSet.forEach(({ name, value }) => {\n            request.cookies.set(name, value);\n          });\n\n          response = NextResponse.next({ request });\n\n          cookiesToSet.forEach(({ name, value, options }) => {\n            response.cookies.set(name, value, options);\n          });\n        },\n      },\n    });\n\n    // ── 3. Refresh session (required to keep tokens alive) ────────\n    const {\n      data: { user },\n    } = await supabase.auth.getUser();\n\n    const { pathname } = request.nextUrl;\n\n    // ── 4. Find the matching route config ─────────────────────────\n    const matchedRoute = findMatchingRoute(routes, pathname);\n\n    // No matching route → not a protected path, pass through.\n    if (!matchedRoute) {\n      return response;\n    }\n\n    // ── 5. Check authentication ───────────────────────────────────\n    if (!user) {\n      const loginUrl = new URL(redirectTo, request.url);\n      loginUrl.searchParams.set(\"next\", pathname);\n      return NextResponse.redirect(loginUrl);\n    }\n\n    // ── 6. Check role-based access ────────────────────────────────\n    const userRole = extractRole(user, roleExtractor);\n\n    if (!hasRequiredRole(userRole, matchedRoute.allowedRoles)) {\n      // User is logged in but lacks the required role.\n      const forbiddenUrl = new URL(redirectTo, request.url);\n      forbiddenUrl.searchParams.set(\"error\", \"forbidden\");\n      forbiddenUrl.searchParams.set(\"next\", pathname);\n      return NextResponse.redirect(forbiddenUrl);\n    }\n\n    // ── 7. Success callback ───────────────────────────────────────\n    if (onAuthSuccess) {\n      await onAuthSuccess({\n        id: user.id,\n        email: user.email ?? undefined,\n        role: userRole,\n      });\n    }\n\n    return response;\n  };\n}\n","import { createServerClient, type CookieOptions } from \"@supabase/ssr\";\nimport { cookies } from \"next/headers\";\nimport type { SupabaseClient } from \"@supabase/supabase-js\";\n\nimport type { ActionResponse, SupaError } from \"../../types\";\nimport { handleSupaError } from \"../../shared/utils/error-handler\";\n\n/**\n * Create a type-safe Server Action that automatically:\n * 1. Initialises a Supabase server client (with cookies)\n * 2. Wraps execution in try/catch\n * 3. Returns a standardised `{ data, error }` response\n *\n * @example\n * ```ts\n * // app/actions/profile.ts\n * \"use server\";\n * import { createAction } from \"next-supa-utils/server\";\n *\n * export const getProfile = createAction(async (supabase, userId: string) => {\n *   const { data, error } = await supabase\n *     .from(\"profiles\")\n *     .select(\"*\")\n *     .eq(\"id\", userId)\n *     .single();\n *\n *   if (error) throw error;\n *   return data;\n * });\n *\n * // Usage in a Server Component or Client Component:\n * const result = await getProfile(\"user-uuid\");\n * if (result.error) { ... }\n * ```\n */\nexport function createAction<TArgs extends unknown[], TResult>(\n  fn: (supabase: SupabaseClient, ...args: TArgs) => Promise<TResult>,\n): (...args: TArgs) => Promise<ActionResponse<TResult>> {\n  return async (...args: TArgs): Promise<ActionResponse<TResult>> => {\n    try {\n      const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;\n      const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;\n\n      if (!supabaseUrl || !supabaseAnonKey) {\n        return {\n          data: null,\n          error: {\n            message:\n              \"Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.\",\n            code: \"CONFIG_ERROR\",\n          },\n        };\n      }\n\n      const cookieStore = await cookies();\n\n      const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n        cookies: {\n          getAll() {\n            return cookieStore.getAll();\n          },\n          setAll(cookiesToSet: { name: string; value: string; options?: CookieOptions }[]) {\n            try {\n              cookiesToSet.forEach(({ name, value, options }) => {\n                cookieStore.set(name, value, options);\n              });\n            } catch {\n              // `cookies().set()` throws when called from a Server Component.\n              // In that context we only need read access — the middleware\n              // handles token refresh.\n            }\n          },\n        },\n      });\n\n      const data = await fn(supabase, ...args);\n\n      return { data, error: null };\n    } catch (caught: unknown) {\n      const error: SupaError = handleSupaError(caught);\n      return { data: null, error };\n    }\n  };\n}\n","import type { SupaError } from \"../../types\";\n\n/**\n * Normalize any thrown value into a consistent `SupaError` shape.\n *\n * Handles:\n * - Supabase `AuthError` / `PostgrestError` (has `.message` and optional `.code` / `.status`)\n * - Standard `Error` instances\n * - Plain strings\n * - Unknown values (fallback)\n */\nexport function handleSupaError(error: unknown): SupaError {\n  // ── Supabase errors & standard Error instances ──────────────────\n  if (error instanceof Error) {\n    const record = error as unknown as Record<string, unknown>;\n    return {\n      message: error.message,\n      code: typeof record.code === \"string\" ? record.code : undefined,\n      status: typeof record.status === \"number\" ? record.status : undefined,\n    };\n  }\n\n  // ── Plain object with a message property ────────────────────────\n  if (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"message\" in error &&\n    typeof (error as Record<string, unknown>).message === \"string\"\n  ) {\n    const err = error as Record<string, unknown>;\n    return {\n      message: err.message as string,\n      code: typeof err.code === \"string\" ? err.code : undefined,\n      status: typeof err.status === \"number\" ? err.status : undefined,\n    };\n  }\n\n  // ── String ──────────────────────────────────────────────────────\n  if (typeof error === \"string\") {\n    return { message: error };\n  }\n\n  // ── Fallback ────────────────────────────────────────────────────\n  return { message: \"An unknown error occurred\" };\n}\n"],"mappings":"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","names":["options","createServerClient","createServerClient"]}

package/dist/shared/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/shared/index.ts","../../src/shared/utils/error-handler.ts"],"sourcesContent":["// ── Shared entry point ──────────────────────────────────────────────\n// Re-exports types and utilities used across client & server modules.\n\nexport { handleSupaError } from \"./utils/error-handler\";\n\nexport type {\n  SupaError,\n  ActionResponse,\n  SupaAuthConfig,\n  UseSupaUserReturn,\n  UseSupaSessionReturn,\n} from \"../types\";\n","import type { SupaError } from \"../../types\";\n\n/**\n * Normalize any thrown value into a consistent `SupaError` shape.\n *\n * Handles:\n * - Supabase `AuthError` / `PostgrestError` (has `.message` and optional `.code` / `.status`)\n * - Standard `Error` instances\n * - Plain strings\n * - Unknown values (fallback)\n */\nexport function handleSupaError(error: unknown): SupaError {\n  // ── Supabase errors & standard Error instances ──────────────────\n  if (error instanceof Error) {\n    const record = error as unknown as Record<string, unknown>;\n    return {\n      message: error.message,\n      code: typeof record.code === \"string\" ? record.code : undefined,\n      status: typeof record.status === \"number\" ? record.status : undefined,\n    };\n  }\n\n  // ── Plain object with a message property ────────────────────────\n  if (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"message\" in error &&\n    typeof (error as Record<string, unknown>).message === \"string\"\n  ) {\n    const err = error as Record<string, unknown>;\n    return {\n      message: err.message as string,\n      code: typeof err.code === \"string\" ? err.code : undefined,\n      status: typeof err.status === \"number\" ? err.status : undefined,\n    };\n  }\n\n  // ── String ──────────────────────────────────────────────────────\n  if (typeof error === \"string\") {\n    return { message: error };\n  }\n\n  // ── Fallback ────────────────────────────────────────────────────\n  return { message: \"An unknown error occurred\" };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACWO,SAAS,gBAAgB,OAA2B;AAEzD,MAAI,iBAAiB,OAAO;AAC1B,UAAM,SAAS;AACf,WAAO;AAAA,MACL,SAAS,MAAM;AAAA,MACf,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,OAAO;AAAA,MACtD,QAAQ,OAAO,OAAO,WAAW,WAAW,OAAO,SAAS;AAAA,IAC9D;AAAA,EACF;AAGA,MACE,OAAO,UAAU,YACjB,UAAU,QACV,aAAa,SACb,OAAQ,MAAkC,YAAY,UACtD;AACA,UAAM,MAAM;AACZ,WAAO;AAAA,MACL,SAAS,IAAI;AAAA,MACb,MAAM,OAAO,IAAI,SAAS,WAAW,IAAI,OAAO;AAAA,MAChD,QAAQ,OAAO,IAAI,WAAW,WAAW,IAAI,SAAS;AAAA,IACxD;AAAA,EACF;AAGA,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO,EAAE,SAAS,MAAM;AAAA,EAC1B;AAGA,SAAO,EAAE,SAAS,4BAA4B;AAChD;","names":[]}
+{"version":3,"sources":["../../src/shared/index.ts","../../src/shared/utils/error-handler.ts"],"sourcesContent":["// ── Shared entry point ──────────────────────────────────────────────\n// Re-exports types and utilities used across client & server modules.\n\nexport { handleSupaError } from \"./utils/error-handler\";\n\nexport type {\n  SupaError,\n  ActionResponse,\n  MiddlewareOptions,\n  RouteConfig,\n  UseSupaUserReturn,\n  UseSupaSessionReturn,\n} from \"../types\";\n","import type { SupaError } from \"../../types\";\n\n/**\n * Normalize any thrown value into a consistent `SupaError` shape.\n *\n * Handles:\n * - Supabase `AuthError` / `PostgrestError` (has `.message` and optional `.code` / `.status`)\n * - Standard `Error` instances\n * - Plain strings\n * - Unknown values (fallback)\n */\nexport function handleSupaError(error: unknown): SupaError {\n  // ── Supabase errors & standard Error instances ──────────────────\n  if (error instanceof Error) {\n    const record = error as unknown as Record<string, unknown>;\n    return {\n      message: error.message,\n      code: typeof record.code === \"string\" ? record.code : undefined,\n      status: typeof record.status === \"number\" ? record.status : undefined,\n    };\n  }\n\n  // ── Plain object with a message property ────────────────────────\n  if (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"message\" in error &&\n    typeof (error as Record<string, unknown>).message === \"string\"\n  ) {\n    const err = error as Record<string, unknown>;\n    return {\n      message: err.message as string,\n      code: typeof err.code === \"string\" ? err.code : undefined,\n      status: typeof err.status === \"number\" ? err.status : undefined,\n    };\n  }\n\n  // ── String ──────────────────────────────────────────────────────\n  if (typeof error === \"string\") {\n    return { message: error };\n  }\n\n  // ── Fallback ────────────────────────────────────────────────────\n  return { message: \"An unknown error occurred\" };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACWO,SAAS,gBAAgB,OAA2B;AAEzD,MAAI,iBAAiB,OAAO;AAC1B,UAAM,SAAS;AACf,WAAO;AAAA,MACL,SAAS,MAAM;AAAA,MACf,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,OAAO;AAAA,MACtD,QAAQ,OAAO,OAAO,WAAW,WAAW,OAAO,SAAS;AAAA,IAC9D;AAAA,EACF;AAGA,MACE,OAAO,UAAU,YACjB,UAAU,QACV,aAAa,SACb,OAAQ,MAAkC,YAAY,UACtD;AACA,UAAM,MAAM;AACZ,WAAO;AAAA,MACL,SAAS,IAAI;AAAA,MACb,MAAM,OAAO,IAAI,SAAS,WAAW,IAAI,OAAO;AAAA,MAChD,QAAQ,OAAO,IAAI,WAAW,WAAW,IAAI,SAAS;AAAA,IACxD;AAAA,EACF;AAGA,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO,EAAE,SAAS,MAAM;AAAA,EAC1B;AAGA,SAAO,EAAE,SAAS,4BAA4B;AAChD;","names":[]}

package/dist/shared/index.d.cts

@@ -14,32 +14,69 @@ type ActionResponse<T> = {
     data: null;
     error: SupaError;
 };
-interface SupaAuthConfig {
+/**
+ * Defines a protected route with optional role-based access control.
+ *
+ * @example
+ * ```ts
+ * { path: "/admin/:path*", allowedRoles: ["admin", "super_admin"] }
+ * ```
+ */
+interface RouteConfig {
     /**
-     * Route prefixes that require an authenticated user.
-     * Supports simple prefix matching.
+     * Route pattern to match.
      *
-     * @example ["/dashboard", "/admin", "/settings"]
+     * Supports:
+     * - Exact paths: `"/settings"`
+     * - Prefix matching: `"/dashboard"` matches `/dashboard/anything`
+     * - Wildcards: `"/admin/:path*"` matches `/admin/users`, `/admin/settings/edit`, etc.
      */
-    protectedRoutes: string[];
+    path: string;
     /**
-     * Where to redirect unauthenticated users.
+     * Roles that are allowed to access this route.
+     *
+     * - If **omitted or empty**, any *authenticated* user can access the route.
+     * - If **provided**, only users whose role is in this list are allowed.
+     *
+     * @example ["admin", "editor"]
+     */
+    allowedRoles?: string[];
+}
+/**
+ * Configuration for the `withSupaAuth` middleware.
+ */
+interface MiddlewareOptions {
+    /**
+     * Protected route definitions. Each entry can optionally restrict access
+     * to specific roles via `allowedRoles`.
+     */
+    routes: RouteConfig[];
+    /**
+     * Where to redirect unauthenticated or unauthorized users.
      * @default "/login"
      */
     redirectTo?: string;
     /**
-     * Routes that are always public, even if they match a protected prefix.
+     * Strategy for extracting the user's role from the Supabase user object.
+     *
+     * - `"user_metadata"` — reads `user.user_metadata.role`
+     * - `"app_metadata"` — reads `user.app_metadata.role`
+     * - A custom function for advanced scenarios (e.g. multiple roles, JWT claims).
      *
-     * @example ["/admin/login"]
+     * @default "user_metadata"
      */
-    publicRoutes?: string[];
+    roleExtractor?: "user_metadata" | "app_metadata" | ((user: {
+        user_metadata: Record<string, unknown>;
+        app_metadata: Record<string, unknown>;
+    }) => string | string[] | undefined);
     /**
-     * Optional callback invoked after session refresh,
-     * before the redirect decision. Useful for custom logging or headers.
+     * Optional callback invoked when a user is authenticated and authorized.
+     * Useful for logging, analytics, or injecting custom response headers.
      */
     onAuthSuccess?: (user: {
         id: string;
         email?: string;
+        role?: string | string[];
     }) => void | Promise<void>;
 }
 interface UseSupaUserReturn {
@@ -64,4 +101,4 @@ interface UseSupaSessionReturn {
  */
 declare function handleSupaError(error: unknown): SupaError;
 
-export { type ActionResponse, type SupaAuthConfig, type SupaError, type UseSupaSessionReturn, type UseSupaUserReturn, handleSupaError };
+export { type ActionResponse, type MiddlewareOptions, type RouteConfig, type SupaError, type UseSupaSessionReturn, type UseSupaUserReturn, handleSupaError };

package/dist/shared/index.d.ts

@@ -14,32 +14,69 @@ type ActionResponse<T> = {
     data: null;
     error: SupaError;
 };
-interface SupaAuthConfig {
+/**
+ * Defines a protected route with optional role-based access control.
+ *
+ * @example
+ * ```ts
+ * { path: "/admin/:path*", allowedRoles: ["admin", "super_admin"] }
+ * ```
+ */
+interface RouteConfig {
     /**
-     * Route prefixes that require an authenticated user.
-     * Supports simple prefix matching.
+     * Route pattern to match.
      *
-     * @example ["/dashboard", "/admin", "/settings"]
+     * Supports:
+     * - Exact paths: `"/settings"`
+     * - Prefix matching: `"/dashboard"` matches `/dashboard/anything`
+     * - Wildcards: `"/admin/:path*"` matches `/admin/users`, `/admin/settings/edit`, etc.
      */
-    protectedRoutes: string[];
+    path: string;
     /**
-     * Where to redirect unauthenticated users.
+     * Roles that are allowed to access this route.
+     *
+     * - If **omitted or empty**, any *authenticated* user can access the route.
+     * - If **provided**, only users whose role is in this list are allowed.
+     *
+     * @example ["admin", "editor"]
+     */
+    allowedRoles?: string[];
+}
+/**
+ * Configuration for the `withSupaAuth` middleware.
+ */
+interface MiddlewareOptions {
+    /**
+     * Protected route definitions. Each entry can optionally restrict access
+     * to specific roles via `allowedRoles`.
+     */
+    routes: RouteConfig[];
+    /**
+     * Where to redirect unauthenticated or unauthorized users.
      * @default "/login"
      */
     redirectTo?: string;
     /**
-     * Routes that are always public, even if they match a protected prefix.
+     * Strategy for extracting the user's role from the Supabase user object.
+     *
+     * - `"user_metadata"` — reads `user.user_metadata.role`
+     * - `"app_metadata"` — reads `user.app_metadata.role`
+     * - A custom function for advanced scenarios (e.g. multiple roles, JWT claims).
      *
-     * @example ["/admin/login"]
+     * @default "user_metadata"
      */
-    publicRoutes?: string[];
+    roleExtractor?: "user_metadata" | "app_metadata" | ((user: {
+        user_metadata: Record<string, unknown>;
+        app_metadata: Record<string, unknown>;
+    }) => string | string[] | undefined);
     /**
-     * Optional callback invoked after session refresh,
-     * before the redirect decision. Useful for custom logging or headers.
+     * Optional callback invoked when a user is authenticated and authorized.
+     * Useful for logging, analytics, or injecting custom response headers.
      */
     onAuthSuccess?: (user: {
         id: string;
         email?: string;
+        role?: string | string[];
     }) => void | Promise<void>;
 }
 interface UseSupaUserReturn {
@@ -64,4 +101,4 @@ interface UseSupaSessionReturn {
  */
 declare function handleSupaError(error: unknown): SupaError;
 
-export { type ActionResponse, type SupaAuthConfig, type SupaError, type UseSupaSessionReturn, type UseSupaUserReturn, handleSupaError };
+export { type ActionResponse, type MiddlewareOptions, type RouteConfig, type SupaError, type UseSupaSessionReturn, type UseSupaUserReturn, handleSupaError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-supa-utils",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Eliminate Supabase boilerplate in Next.js App Router — hooks, middleware helpers, and server action wrappers.",
   "license": "MIT",
   "type": "module",