next-supa-utils 0.1.0

package/README.md

@@ -0,0 +1,326 @@
+<p align="center">
+  <h1 align="center">next-supa-utils</h1>
+  <p align="center">
+    Eliminate Supabase boilerplate in Next.js App Router.<br/>
+    Hooks, middleware helpers, and server action wrappers — all type-safe.
+  </p>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#contributing">Contributing</a> •
+  <a href="#license">License</a>
+</p>
+
+---
+
+## Why?
+
+Every Next.js + Supabase project ends up with the same boilerplate:
+
+- 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
+
+**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
+
+```bash
+npm install next-supa-utils
+```
+
+### Peer Dependencies
+
+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
+
+Add these to your `.env.local`:
+
+```env
+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
+
+### 1. Protect Routes with Middleware
+
+```ts
+// middleware.ts
+import { withSupaAuth } from "next-supa-utils/server";
+
+export default withSupaAuth({
+  protectedRoutes: ["/dashboard", "/admin", "/settings"],
+  redirectTo: "/login",
+  publicRoutes: ["/admin/login"],
+});
+
+export const config = {
+  matcher: [
+    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
+  ],
+};
+```
+
+### 2. Create Type-Safe Server Actions
+
+```ts
+// app/actions/profile.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;
+  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);
+}
+```
+
+### 3. Use Auth State in Client Components
+
+```tsx
+"use client";
+import { useSupaUser } from "next-supa-utils/client";
+
+export default function Avatar() {
+  const { user, loading, error } = useSupaUser();
+
+  if (loading) return <p>Loading…</p>;
+  if (error) return <p>Error: {error.message}</p>;
+  if (!user) return <p>Not signed in</p>;
+
+  return <p>Hello, {user.email}!</p>;
+}
+```
+
+---
+
+## API Reference
+
+### Server — `next-supa-utils/server`
+
+#### `withSupaAuth(config)`
+
+Creates a Next.js middleware function that handles session refresh and route protection.
+
+**Parameters:**
+
+| Property | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `protectedRoutes` | `string[]` | ✅ | — | Route prefixes that require authentication |
+| `redirectTo` | `string` | — | `"/login"` | Where to redirect unauthenticated users |
+| `publicRoutes` | `string[]` | — | `[]` | Routes that are always public, even if matching a protected prefix |
+| `onAuthSuccess` | `(user: { id: string; email?: string }) => void \| Promise<void>` | — | — | Optional callback after successful auth verification |
+
+**Returns:** `(request: NextRequest) => Promise<NextResponse>`
+
+**Behavior:**
+1. Creates a Supabase server client with proper cookie forwarding
+2. Calls `supabase.auth.getUser()` to refresh the session
+3. If the current path matches `publicRoutes`, allows access immediately
+4. If the current path matches `protectedRoutes` and the user is not authenticated, redirects to `redirectTo` with a `?next=<original_path>` query parameter
+5. Calls `onAuthSuccess` if the user is authenticated and the callback is provided
+
+---
+
+#### `createAction(fn)`
+
+Wraps an async function into a server action with automatic Supabase client initialization and error handling.
+
+**Signature:**
+
+```ts
+function createAction<TArgs extends unknown[], TResult>(
+  fn: (supabase: SupabaseClient, ...args: TArgs) => Promise<TResult>
+): (...args: TArgs) => Promise<ActionResponse<TResult>>
+```
+
+**Returns:** `ActionResponse<TResult>` — a discriminated union:
+
+```ts
+// On success:
+{ data: TResult; error: null }
+
+// On failure:
+{ data: null; error: SupaError }
+```
+
+**Behavior:**
+1. Creates a Supabase server client using `cookies()` from `next/headers`
+2. Passes the client as the first argument to your function
+3. Wraps execution in try/catch — any thrown error is normalized into a `SupaError`
+
+---
+
+### Client — `next-supa-utils/client`
+
+> ⚠️ All client exports include the `"use client"` directive. They must be used inside Client Components only.
+
+#### `useSupaUser()`
+
+React hook that provides the current authenticated user and subscribes to auth state changes.
+
+**Returns:** `UseSupaUserReturn`
+
+| Property | Type | Description |
+|---|---|---|
+| `user` | `User \| null` | The current Supabase user object, or `null` if not authenticated |
+| `loading` | `boolean` | `true` while the initial fetch is in progress |
+| `error` | `SupaError \| null` | Error details if the fetch failed |
+
+**Behavior:**
+1. Creates a browser client via `createBrowserClient` from `@supabase/ssr`
+2. Calls `supabase.auth.getUser()` on mount
+3. Subscribes to `onAuthStateChange` for real-time updates (sign in, sign out, token refresh)
+4. Cleans up the subscription on unmount
+
+---
+
+#### `useSupaSession()`
+
+React hook that provides the current session (access token, refresh token, expiry) and subscribes to auth state changes.
+
+**Returns:** `UseSupaSessionReturn`
+
+| Property | Type | Description |
+|---|---|---|
+| `session` | `Session \| null` | The current Supabase session, or `null` if not authenticated |
+| `loading` | `boolean` | `true` while the initial fetch is in progress |
+| `error` | `SupaError \| null` | Error details if the fetch failed |
+
+---
+
+### Shared — `next-supa-utils`
+
+#### `handleSupaError(error)`
+
+Normalizes any thrown value into a consistent `SupaError` shape. Used internally by `createAction` and the hooks, but also exported for direct use.
+
+```ts
+function handleSupaError(error: unknown): SupaError
+```
+
+**Handles:**
+- Supabase `AuthError` / `PostgrestError` (extracts `message`, `code`, `status`)
+- Standard `Error` instances
+- Plain objects with a `message` property
+- Strings
+- Unknown values (fallback: `"An unknown error occurred"`)
+
+---
+
+### Types
+
+```ts
+interface SupaError {
+  message: string;
+  code?: string;
+  status?: number;
+}
+
+type ActionResponse<T> =
+  | { data: T; error: null }
+  | { data: null; error: SupaError };
+
+interface SupaAuthConfig {
+  protectedRoutes: string[];
+  redirectTo?: string;
+  publicRoutes?: string[];
+  onAuthSuccess?: (user: { id: string; email?: string }) => void | Promise<void>;
+}
+```
+
+---
+
+## Project Structure
+
+```
+src/
+├── client/              # "use client" — browser-only code
+│   ├── hooks/
+│   │   ├── useSupaUser.ts
+│   │   └── useSupaSession.ts
+│   └── index.ts
+├── server/              # Server-only (Node/Edge runtime)
+│   ├── middleware/
+│   │   └── withSupaAuth.ts
+│   ├── actions/
+│   │   └── actionWrapper.ts
+│   └── index.ts
+├── shared/              # Isomorphic utilities
+│   ├── utils/
+│   │   └── error-handler.ts
+│   └── index.ts
+└── types/
+    └── index.ts
+```
+
+## Import Paths
+
+| Import | Environment | Contains |
+|---|---|---|
+| `next-supa-utils/client` | Client Components | `useSupaUser`, `useSupaSession` |
+| `next-supa-utils/server` | Server Components, Middleware, Server Actions | `withSupaAuth`, `createAction` |
+| `next-supa-utils` | Anywhere | `handleSupaError`, all types |
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Install dependencies (`npm install`)
+4. Make your changes
+5. Run the type checker (`npm run typecheck`)
+6. Build the project (`npm run build`)
+7. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+## License
+
+[MIT](LICENSE)

package/dist/client/index.cjs

@@ -0,0 +1,154 @@
+"use client";
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  useSupaSession: () => useSupaSession,
+  useSupaUser: () => useSupaUser
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/client/hooks/useSupaUser.ts
+var import_react = require("react");
+var import_ssr = require("@supabase/ssr");
+
+// src/shared/utils/error-handler.ts
+function handleSupaError(error) {
+  if (error instanceof Error) {
+    const record = error;
+    return {
+      message: error.message,
+      code: typeof record.code === "string" ? record.code : void 0,
+      status: typeof record.status === "number" ? record.status : void 0
+    };
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    const err = error;
+    return {
+      message: err.message,
+      code: typeof err.code === "string" ? err.code : void 0,
+      status: typeof err.status === "number" ? err.status : void 0
+    };
+  }
+  if (typeof error === "string") {
+    return { message: error };
+  }
+  return { message: "An unknown error occurred" };
+}
+
+// src/client/hooks/useSupaUser.ts
+function useSupaUser() {
+  const [state, setState] = (0, import_react.useState)({
+    user: null,
+    loading: true,
+    error: null
+  });
+  (0, import_react.useEffect)(() => {
+    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
+    const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+    if (!supabaseUrl || !supabaseAnonKey) {
+      setState({
+        user: null,
+        loading: false,
+        error: {
+          message: "Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.",
+          code: "CONFIG_ERROR"
+        }
+      });
+      return;
+    }
+    const supabase = (0, import_ssr.createBrowserClient)(supabaseUrl, supabaseAnonKey);
+    supabase.auth.getUser().then(({ data, error }) => {
+      setState({
+        user: data.user,
+        loading: false,
+        error: error ? handleSupaError(error) : null
+      });
+    });
+    const {
+      data: { subscription }
+    } = supabase.auth.onAuthStateChange((_event, session) => {
+      setState((prev) => ({
+        ...prev,
+        user: session?.user ?? null,
+        loading: false
+      }));
+    });
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, []);
+  return state;
+}
+
+// src/client/hooks/useSupaSession.ts
+var import_react2 = require("react");
+var import_ssr2 = require("@supabase/ssr");
+function useSupaSession() {
+  const [state, setState] = (0, import_react2.useState)({
+    session: null,
+    loading: true,
+    error: null
+  });
+  (0, import_react2.useEffect)(() => {
+    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
+    const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+    if (!supabaseUrl || !supabaseAnonKey) {
+      setState({
+        session: null,
+        loading: false,
+        error: {
+          message: "Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY environment variables.",
+          code: "CONFIG_ERROR"
+        }
+      });
+      return;
+    }
+    const supabase = (0, import_ssr2.createBrowserClient)(supabaseUrl, supabaseAnonKey);
+    supabase.auth.getSession().then(({ data, error }) => {
+      setState({
+        session: data.session,
+        loading: false,
+        error: error ? handleSupaError(error) : null
+      });
+    });
+    const {
+      data: { subscription }
+    } = supabase.auth.onAuthStateChange((_event, session) => {
+      setState((prev) => ({
+        ...prev,
+        session,
+        loading: false
+      }));
+    });
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, []);
+  return state;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useSupaSession,
+  useSupaUser
+});
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.ts","../../src/client/hooks/useSupaUser.ts","../../src/shared/utils/error-handler.ts","../../src/client/hooks/useSupaSession.ts"],"sourcesContent":["\"use client\";\n\n// ── Client entry point ──────────────────────────────────────────────\n// This module MUST only be imported in Client Components.\n// The \"use client\" directive ensures Next.js treats the entire\n// sub-tree as client-side code.\n\nexport { useSupaUser } from \"./hooks/useSupaUser\";\nexport { useSupaSession } from \"./hooks/useSupaSession\";\n\n// Re-export types consumers commonly need alongside client helpers.\nexport type {\n  UseSupaUserReturn,\n  UseSupaSessionReturn,\n  SupaError,\n} from \"../types\";\n","\"use client\";\n\nimport { useEffect, useState } from \"react\";\nimport { createBrowserClient } from \"@supabase/ssr\";\n\nimport type { UseSupaUserReturn } from \"../../types\";\nimport { handleSupaError } from \"../../shared/utils/error-handler\";\n\n/**\n * React hook that provides the current Supabase user and\n * subscribes to real-time auth state changes.\n *\n * Must be used inside a Client Component (`\"use client\"`).\n *\n * @example\n * ```tsx\n * \"use client\";\n * import { useSupaUser } from \"next-supa-utils/client\";\n *\n * export default function Avatar() {\n *   const { user, loading, error } = useSupaUser();\n *\n *   if (loading) return <p>Loading…</p>;\n *   if (error)  return <p>Error: {error.message}</p>;\n *   if (!user)  return <p>Not signed in</p>;\n *\n *   return <p>Hello, {user.email}</p>;\n * }\n * ```\n */\nexport function useSupaUser(): UseSupaUserReturn {\n  const [state, setState] = useState<UseSupaUserReturn>({\n    user: null,\n    loading: true,\n    error: null,\n  });\n\n  useEffect(() => {\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      setState({\n        user: null,\n        loading: false,\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      return;\n    }\n\n    const supabase = createBrowserClient(supabaseUrl, supabaseAnonKey);\n\n    // ── Initial fetch ─────────────────────────────────────────────\n    supabase.auth.getUser().then(({ data, error }) => {\n      setState({\n        user: data.user,\n        loading: false,\n        error: error ? handleSupaError(error) : null,\n      });\n    });\n\n    // ── Subscribe to auth state changes ───────────────────────────\n    const {\n      data: { subscription },\n    } = supabase.auth.onAuthStateChange((_event, session) => {\n      setState((prev) => ({\n        ...prev,\n        user: session?.user ?? null,\n        loading: false,\n      }));\n    });\n\n    return () => {\n      subscription.unsubscribe();\n    };\n  }, []);\n\n  return state;\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","\"use client\";\n\nimport { useEffect, useState } from \"react\";\nimport { createBrowserClient } from \"@supabase/ssr\";\nimport type { Session } from \"@supabase/supabase-js\";\n\nimport type { UseSupaSessionReturn } from \"../../types\";\nimport { handleSupaError } from \"../../shared/utils/error-handler\";\n\n/**\n * React hook that provides the current Supabase session and\n * subscribes to real-time auth state changes.\n *\n * Must be used inside a Client Component (`\"use client\"`).\n *\n * @example\n * ```tsx\n * \"use client\";\n * import { useSupaSession } from \"next-supa-utils/client\";\n *\n * export default function TokenDisplay() {\n *   const { session, loading, error } = useSupaSession();\n *\n *   if (loading)   return <p>Loading…</p>;\n *   if (error)     return <p>Error: {error.message}</p>;\n *   if (!session)  return <p>No active session</p>;\n *\n *   return <p>Token expires at: {session.expires_at}</p>;\n * }\n * ```\n */\nexport function useSupaSession(): UseSupaSessionReturn {\n  const [state, setState] = useState<UseSupaSessionReturn>({\n    session: null,\n    loading: true,\n    error: null,\n  });\n\n  useEffect(() => {\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      setState({\n        session: null,\n        loading: false,\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      return;\n    }\n\n    const supabase = createBrowserClient(supabaseUrl, supabaseAnonKey);\n\n    // ── Initial fetch ─────────────────────────────────────────────\n    supabase.auth.getSession().then(({ data, error }) => {\n      setState({\n        session: data.session,\n        loading: false,\n        error: error ? handleSupaError(error) : null,\n      });\n    });\n\n    // ── Subscribe to auth state changes ───────────────────────────\n    const {\n      data: { subscription },\n    } = supabase.auth.onAuthStateChange((_event, session: Session | null) => {\n      setState((prev) => ({\n        ...prev,\n        session,\n        loading: false,\n      }));\n    });\n\n    return () => {\n      subscription.unsubscribe();\n    };\n  }, []);\n\n  return state;\n}\n"],"mappings":"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","names":["import_react","import_ssr"]}

package/dist/client/index.d.cts

@@ -0,0 +1,68 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+
+/** Standardized error shape returned by all next-supa-utils helpers. */
+interface SupaError {
+    message: string;
+    code?: string;
+    status?: number;
+}
+interface UseSupaUserReturn {
+    user: Awaited<ReturnType<SupabaseClient["auth"]["getUser"]>>["data"]["user"];
+    loading: boolean;
+    error: SupaError | null;
+}
+interface UseSupaSessionReturn {
+    session: Awaited<ReturnType<SupabaseClient["auth"]["getSession"]>>["data"]["session"];
+    loading: boolean;
+    error: SupaError | null;
+}
+
+/**
+ * React hook that provides the current Supabase user and
+ * subscribes to real-time auth state changes.
+ *
+ * Must be used inside a Client Component (`"use client"`).
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useSupaUser } from "next-supa-utils/client";
+ *
+ * export default function Avatar() {
+ *   const { user, loading, error } = useSupaUser();
+ *
+ *   if (loading) return <p>Loading…</p>;
+ *   if (error)  return <p>Error: {error.message}</p>;
+ *   if (!user)  return <p>Not signed in</p>;
+ *
+ *   return <p>Hello, {user.email}</p>;
+ * }
+ * ```
+ */
+declare function useSupaUser(): UseSupaUserReturn;
+
+/**
+ * React hook that provides the current Supabase session and
+ * subscribes to real-time auth state changes.
+ *
+ * Must be used inside a Client Component (`"use client"`).
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useSupaSession } from "next-supa-utils/client";
+ *
+ * export default function TokenDisplay() {
+ *   const { session, loading, error } = useSupaSession();
+ *
+ *   if (loading)   return <p>Loading…</p>;
+ *   if (error)     return <p>Error: {error.message}</p>;
+ *   if (!session)  return <p>No active session</p>;
+ *
+ *   return <p>Token expires at: {session.expires_at}</p>;
+ * }
+ * ```
+ */
+declare function useSupaSession(): UseSupaSessionReturn;
+
+export { type SupaError, type UseSupaSessionReturn, type UseSupaUserReturn, useSupaSession, useSupaUser };

package/dist/client/index.d.ts

@@ -0,0 +1,68 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+
+/** Standardized error shape returned by all next-supa-utils helpers. */
+interface SupaError {
+    message: string;
+    code?: string;
+    status?: number;
+}
+interface UseSupaUserReturn {
+    user: Awaited<ReturnType<SupabaseClient["auth"]["getUser"]>>["data"]["user"];
+    loading: boolean;
+    error: SupaError | null;
+}
+interface UseSupaSessionReturn {
+    session: Awaited<ReturnType<SupabaseClient["auth"]["getSession"]>>["data"]["session"];
+    loading: boolean;
+    error: SupaError | null;
+}
+
+/**
+ * React hook that provides the current Supabase user and
+ * subscribes to real-time auth state changes.
+ *
+ * Must be used inside a Client Component (`"use client"`).
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useSupaUser } from "next-supa-utils/client";
+ *
+ * export default function Avatar() {
+ *   const { user, loading, error } = useSupaUser();
+ *
+ *   if (loading) return <p>Loading…</p>;
+ *   if (error)  return <p>Error: {error.message}</p>;
+ *   if (!user)  return <p>Not signed in</p>;
+ *
+ *   return <p>Hello, {user.email}</p>;
+ * }
+ * ```
+ */
+declare function useSupaUser(): UseSupaUserReturn;
+
+/**
+ * React hook that provides the current Supabase session and
+ * subscribes to real-time auth state changes.
+ *
+ * Must be used inside a Client Component (`"use client"`).
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useSupaSession } from "next-supa-utils/client";
+ *
+ * export default function TokenDisplay() {
+ *   const { session, loading, error } = useSupaSession();
+ *
+ *   if (loading)   return <p>Loading…</p>;
+ *   if (error)     return <p>Error: {error.message}</p>;
+ *   if (!session)  return <p>No active session</p>;
+ *
+ *   return <p>Token expires at: {session.expires_at}</p>;
+ * }
+ * ```
+ */
+declare function useSupaSession(): UseSupaSessionReturn;
+
+export { type SupaError, type UseSupaSessionReturn, type UseSupaUserReturn, useSupaSession, useSupaUser };