naystack 1.5.9 → 1.5.11

package/dist/auth/index.esm.js

@@ -125,7 +125,6 @@ async function checkAuthStatus(redirectUnauthorizedURL) {
 
 // src/auth/email/utils.ts
 import { verify as verify2 } from "jsonwebtoken";
-import { cookies as cookies2 } from "next/headers";
 
 // src/auth/utils/errors.ts
 import { NextResponse as NextResponse2 } from "next/server";
@@ -202,19 +201,6 @@ var getContext = (req) => {
   }
   return { userId: null };
 };
-async function logout(data) {
-  const Cookie = await cookies2();
-  Cookie.delete(REFRESH_COOKIE_NAME);
-  await fetch(getEnv("NEXT_PUBLIC_EMAIL_AUTH_ENDPOINT" /* NEXT_PUBLIC_EMAIL_AUTH_ENDPOINT */), {
-    method: "DELETE",
-    credentials: "include",
-    body: JSON.stringify(data)
-  });
-}
-async function getCurrentRefreshToken() {
-  const Cookie = await cookies2();
-  return Cookie.get(REFRESH_COOKIE_NAME)?.value;
-}
 
 // src/auth/email/routes/delete.ts
 var getDeleteRoute = (options) => async (req) => {
@@ -498,18 +484,16 @@ function initInstagramAuth(props) {
 }
 
 // src/auth/utils/token.ts
-import { cookies as cookies3 } from "next/headers";
+import { cookies as cookies2 } from "next/headers";
 async function getRefreshToken() {
-  const Cookie = await cookies3();
+  const Cookie = await cookies2();
   return Cookie.get(REFRESH_COOKIE_NAME)?.value || null;
 }
 export {
   checkAuthStatus,
   getContext,
-  getCurrentRefreshToken,
   getEmailAuthRoutes,
   getRefreshToken,
   initGoogleAuth,
-  initInstagramAuth,
-  logout
+  initInstagramAuth
 };

package/dist/auth/instagram/client.d.mts

@@ -1,3 +1,22 @@
+/**
+ * Creates a function that builds the Instagram OAuth authorization URL for a given state token.
+ * The state token is typically the user's access token, used to link the Instagram account to the logged-in user.
+ *
+ * @param redirectURL - The OAuth redirect URI registered with Instagram (e.g. `NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT`).
+ * @returns A function `(stateToken: string) => string` that returns the full authorization URL.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramAuthorizationURLSetup } from "naystack/auth/instagram/client";
+ *
+ * const getAuthURL = getInstagramAuthorizationURLSetup("/api/instagram");
+ * const url = getAuthURL(userAccessToken);
+ * // => "https://www.instagram.com/oauth/authorize?client_id=...&state=...&redirect_uri=..."
+ * window.location.href = url;
+ * ```
+ *
+ * @category Auth
+ */
 declare const getInstagramAuthorizationURLSetup: (redirectURL: string) => (token: string) => string;
 
 export { getInstagramAuthorizationURLSetup };

package/dist/auth/instagram/client.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Creates a function that builds the Instagram OAuth authorization URL for a given state token.
+ * The state token is typically the user's access token, used to link the Instagram account to the logged-in user.
+ *
+ * @param redirectURL - The OAuth redirect URI registered with Instagram (e.g. `NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT`).
+ * @returns A function `(stateToken: string) => string` that returns the full authorization URL.
+ *
+ * @example
+ * ```ts
+ * import { getInstagramAuthorizationURLSetup } from "naystack/auth/instagram/client";
+ *
+ * const getAuthURL = getInstagramAuthorizationURLSetup("/api/instagram");
+ * const url = getAuthURL(userAccessToken);
+ * // => "https://www.instagram.com/oauth/authorize?client_id=...&state=...&redirect_uri=..."
+ * window.location.href = url;
+ * ```
+ *
+ * @category Auth
+ */
 declare const getInstagramAuthorizationURLSetup: (redirectURL: string) => (token: string) => string;
 
 export { getInstagramAuthorizationURLSetup };

package/dist/auth/instagram/index.d.mts

@@ -2,12 +2,49 @@ import * as next_server from 'next/server';
 import { getRefreshedAccessToken } from './utils.mjs';
 import { InstagramUser } from '../../socials/instagram/types.mjs';
 
+/**
+ * Options for initializing Instagram OAuth via {@link initInstagramAuth}.
+ *
+ * @property onUser - Called with `(instagramUser, appUserId, accessToken)` after successful OAuth. Return a string to show as error (redirects to `errorRedirectURL`); return `void` on success.
+ * @property successRedirectURL - Where to redirect after successful Instagram auth.
+ * @property errorRedirectURL - Where to redirect on error (with `?error=` query param).
+ * @property refreshKey - Your app secret (e.g. `REFRESH_KEY` env var) used in the flow.
+ *
+ * @category Auth
+ */
 interface InitInstagramAuthOptions {
     onUser: (data: InstagramUser, id: number | null, accessToken: string) => Promise<string | void>;
     successRedirectURL: string;
     errorRedirectURL: string;
     refreshKey: string;
 }
+/**
+ * Initializes Instagram OAuth. Returns a GET handler for the OAuth callback and a helper to refresh long-lived tokens.
+ *
+ * Mount the GET handler on your Instagram auth route (e.g. `app/api/(auth)/instagram/route.ts`).
+ *
+ * Requires env vars: `INSTAGRAM_CLIENT_ID`, `INSTAGRAM_CLIENT_SECRET`, `NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT`.
+ *
+ * @param props - Options. See {@link InitInstagramAuthOptions}.
+ * @returns Object with `GET` (route handler) and `getRefreshedAccessToken` (refreshes a long-lived token).
+ *
+ * @example
+ * ```ts
+ * // app/api/(auth)/instagram/route.ts
+ * import { initInstagramAuth } from "naystack/auth";
+ *
+ * export const { GET, getRefreshedAccessToken } = initInstagramAuth({
+ *   onUser: async (igUser, appUserId, accessToken) => {
+ *     await saveInstagramUser(appUserId, igUser, accessToken);
+ *   },
+ *   successRedirectURL: "/dashboard",
+ *   errorRedirectURL: "/login",
+ *   refreshKey: process.env.REFRESH_KEY!,
+ * });
+ * ```
+ *
+ * @category Auth
+ */
 declare function initInstagramAuth(props: InitInstagramAuthOptions): {
     GET: (req: next_server.NextRequest) => Promise<next_server.NextResponse<unknown>>;
     getRefreshedAccessToken: typeof getRefreshedAccessToken;

package/dist/auth/instagram/index.d.ts

@@ -2,12 +2,49 @@ import * as next_server from 'next/server';
 import { getRefreshedAccessToken } from './utils.js';
 import { InstagramUser } from '../../socials/instagram/types.js';
 
+/**
+ * Options for initializing Instagram OAuth via {@link initInstagramAuth}.
+ *
+ * @property onUser - Called with `(instagramUser, appUserId, accessToken)` after successful OAuth. Return a string to show as error (redirects to `errorRedirectURL`); return `void` on success.
+ * @property successRedirectURL - Where to redirect after successful Instagram auth.
+ * @property errorRedirectURL - Where to redirect on error (with `?error=` query param).
+ * @property refreshKey - Your app secret (e.g. `REFRESH_KEY` env var) used in the flow.
+ *
+ * @category Auth
+ */
 interface InitInstagramAuthOptions {
     onUser: (data: InstagramUser, id: number | null, accessToken: string) => Promise<string | void>;
     successRedirectURL: string;
     errorRedirectURL: string;
     refreshKey: string;
 }
+/**
+ * Initializes Instagram OAuth. Returns a GET handler for the OAuth callback and a helper to refresh long-lived tokens.
+ *
+ * Mount the GET handler on your Instagram auth route (e.g. `app/api/(auth)/instagram/route.ts`).
+ *
+ * Requires env vars: `INSTAGRAM_CLIENT_ID`, `INSTAGRAM_CLIENT_SECRET`, `NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT`.
+ *
+ * @param props - Options. See {@link InitInstagramAuthOptions}.
+ * @returns Object with `GET` (route handler) and `getRefreshedAccessToken` (refreshes a long-lived token).
+ *
+ * @example
+ * ```ts
+ * // app/api/(auth)/instagram/route.ts
+ * import { initInstagramAuth } from "naystack/auth";
+ *
+ * export const { GET, getRefreshedAccessToken } = initInstagramAuth({
+ *   onUser: async (igUser, appUserId, accessToken) => {
+ *     await saveInstagramUser(appUserId, igUser, accessToken);
+ *   },
+ *   successRedirectURL: "/dashboard",
+ *   errorRedirectURL: "/login",
+ *   refreshKey: process.env.REFRESH_KEY!,
+ * });
+ * ```
+ *
+ * @category Auth
+ */
 declare function initInstagramAuth(props: InitInstagramAuthOptions): {
     GET: (req: next_server.NextRequest) => Promise<next_server.NextResponse<unknown>>;
     getRefreshedAccessToken: typeof getRefreshedAccessToken;

package/dist/auth/instagram/route.d.mts

@@ -3,6 +3,11 @@ import { InitInstagramAuthOptions } from './index.mjs';
 import './utils.mjs';
 import '../../socials/instagram/types.mjs';
 
+/**
+ * Returns the GET route handler for Instagram OAuth callback.
+ * @param options - InitInstagramAuthOptions (onUser, redirect URLs)
+ * @returns Async route handler for the OAuth callback
+ */
 declare const getInstagramRoute: ({ successRedirectURL, errorRedirectURL, onUser, }: InitInstagramAuthOptions) => (req: NextRequest) => Promise<NextResponse<unknown>>;
 
 export { getInstagramRoute };

package/dist/auth/instagram/route.d.ts

@@ -3,6 +3,11 @@ import { InitInstagramAuthOptions } from './index.js';
 import './utils.js';
 import '../../socials/instagram/types.js';
 
+/**
+ * Returns the GET route handler for Instagram OAuth callback.
+ * @param options - InitInstagramAuthOptions (onUser, redirect URLs)
+ * @returns Async route handler for the OAuth callback
+ */
 declare const getInstagramRoute: ({ successRedirectURL, errorRedirectURL, onUser, }: InitInstagramAuthOptions) => (req: NextRequest) => Promise<NextResponse<unknown>>;
 
 export { getInstagramRoute };

package/dist/auth/instagram/utils.d.mts

@@ -1,4 +1,17 @@
+/**
+ * Exchanges a long-lived Instagram token for a refreshed token.
+ * @param token - Current long-lived access token
+ * @returns New access token or undefined
+ */
 declare function getRefreshedAccessToken(token: string): Promise<string | undefined>;
+/**
+ * Exchanges an OAuth code for a long-lived Instagram access token.
+ * @param code - OAuth authorization code from redirect
+ * @param redirectURL - Registered redirect URI
+ * @param clientId - Instagram app client id
+ * @param clientSecret - Instagram app client secret
+ * @returns Object with accessToken and userId, or undefined
+ */
 declare function getLongLivedToken(code: string, redirectURL: string, clientId: string, clientSecret: string): Promise<{
     accessToken: string;
     userId: string;

package/dist/auth/instagram/utils.d.ts

@@ -1,4 +1,17 @@
+/**
+ * Exchanges a long-lived Instagram token for a refreshed token.
+ * @param token - Current long-lived access token
+ * @returns New access token or undefined
+ */
 declare function getRefreshedAccessToken(token: string): Promise<string | undefined>;
+/**
+ * Exchanges an OAuth code for a long-lived Instagram access token.
+ * @param code - OAuth authorization code from redirect
+ * @param redirectURL - Registered redirect URI
+ * @param clientId - Instagram app client id
+ * @param clientSecret - Instagram app client secret
+ * @returns Object with accessToken and userId, or undefined
+ */
 declare function getLongLivedToken(code: string, redirectURL: string, clientId: string, clientSecret: string): Promise<{
     accessToken: string;
     userId: string;

package/dist/auth/types.d.mts

@@ -1,9 +1,33 @@
 import { NextResponse } from 'next/server';
 
+/**
+ * Custom error handler for auth routes. Return a NextResponse to send a custom error; otherwise the default response is used.
+ *
+ * @param error - Object with `status` (HTTP code) and `message` (error text).
+ * @returns NextResponse to override the default error, or undefined to use the default.
+ *
+ * @example
+ * ```ts
+ * const onError: ErrorHandler = ({ status, message }) => {
+ *   if (status === 400) return NextResponse.json({ error: message }, { status: 400 });
+ *   return undefined; // Use default handling
+ * };
+ * ```
+ *
+ * @category Auth
+ */
 type ErrorHandler = (error: {
     status: number;
     message: string;
 }) => NextResponse;
+/**
+ * Shape expected from `getUser` / `createUser` callbacks: at least `id` and optional `password` hash, plus any extra fields.
+ *
+ * @property id - User id (numeric primary key).
+ * @property password - Bcrypt-hashed password, or `null` for OAuth-only users.
+ *
+ * @category Auth
+ */
 type UserOutput = {
     id: number;
     password: string | null;

package/dist/auth/types.d.ts

@@ -1,9 +1,33 @@
 import { NextResponse } from 'next/server';
 
+/**
+ * Custom error handler for auth routes. Return a NextResponse to send a custom error; otherwise the default response is used.
+ *
+ * @param error - Object with `status` (HTTP code) and `message` (error text).
+ * @returns NextResponse to override the default error, or undefined to use the default.
+ *
+ * @example
+ * ```ts
+ * const onError: ErrorHandler = ({ status, message }) => {
+ *   if (status === 400) return NextResponse.json({ error: message }, { status: 400 });
+ *   return undefined; // Use default handling
+ * };
+ * ```
+ *
+ * @category Auth
+ */
 type ErrorHandler = (error: {
     status: number;
     message: string;
 }) => NextResponse;
+/**
+ * Shape expected from `getUser` / `createUser` callbacks: at least `id` and optional `password` hash, plus any extra fields.
+ *
+ * @property id - User id (numeric primary key).
+ * @property password - Bcrypt-hashed password, or `null` for OAuth-only users.
+ *
+ * @category Auth
+ */
 type UserOutput = {
     id: number;
     password: string | null;

package/dist/auth/utils/errors.d.mts

@@ -1,6 +1,16 @@
 import { NextResponse } from 'next/server';
 import { ErrorHandler } from '../types.mjs';
 
+/**
+ * Creates a NextResponse for an error, or delegates to a custom `onError` handler if provided.
+ * Used internally by auth routes for consistent error handling.
+ *
+ * @param status - HTTP status code.
+ * @param message - Error message body.
+ * @param onError - Optional custom handler; if it returns a Response, that is used instead of the default.
+ * @returns NextResponse with the given status and message, or the custom handler's response.
+ * @category Auth
+ */
 declare function handleError(status: number, message: string, onError?: ErrorHandler): NextResponse<unknown>;
 
 export { handleError };

package/dist/auth/utils/errors.d.ts

@@ -1,6 +1,16 @@
 import { NextResponse } from 'next/server';
 import { ErrorHandler } from '../types.js';
 
+/**
+ * Creates a NextResponse for an error, or delegates to a custom `onError` handler if provided.
+ * Used internally by auth routes for consistent error handling.
+ *
+ * @param status - HTTP status code.
+ * @param message - Error message body.
+ * @param onError - Optional custom handler; if it returns a Response, that is used instead of the default.
+ * @returns NextResponse with the given status and message, or the custom handler's response.
+ * @category Auth
+ */
 declare function handleError(status: number, message: string, onError?: ErrorHandler): NextResponse<unknown>;
 
 export { handleError };

package/dist/auth/utils/token.d.mts

@@ -1,3 +1,23 @@
+/**
+ * Reads the refresh token from cookies (server-side only). Use this in Server Components, layouts,
+ * or Server Actions to check if the user is authenticated.
+ *
+ * @returns The refresh token string, or `null` if no refresh cookie is present.
+ *
+ * @example
+ * ```ts
+ * import { getRefreshToken } from "naystack/auth";
+ * import { redirect } from "next/navigation";
+ *
+ * export default async function ProtectedLayout({ children }: { children: React.ReactNode }) {
+ *   const token = await getRefreshToken();
+ *   if (!token) return redirect("/login");
+ *   return <div>{children}</div>;
+ * }
+ * ```
+ *
+ * @category Auth
+ */
 declare function getRefreshToken(): Promise<string | null>;
 
 export { getRefreshToken };

package/dist/auth/utils/token.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Reads the refresh token from cookies (server-side only). Use this in Server Components, layouts,
+ * or Server Actions to check if the user is authenticated.
+ *
+ * @returns The refresh token string, or `null` if no refresh cookie is present.
+ *
+ * @example
+ * ```ts
+ * import { getRefreshToken } from "naystack/auth";
+ * import { redirect } from "next/navigation";
+ *
+ * export default async function ProtectedLayout({ children }: { children: React.ReactNode }) {
+ *   const token = await getRefreshToken();
+ *   if (!token) return redirect("/login");
+ *   return <div>{children}</div>;
+ * }
+ * ```
+ *
+ * @category Auth
+ */
 declare function getRefreshToken(): Promise<string | null>;
 
 export { getRefreshToken };

package/dist/client/hooks.d.mts

@@ -1,6 +1,65 @@
 import * as React from 'react';
 
+/**
+ * Tracks when a DOM element enters the viewport and calls a callback.
+ * Uses `IntersectionObserver` with `rootMargin: "100px"` and `threshold: 0.1`.
+ *
+ * Attach the returned ref to the element you want to observe.
+ *
+ * @param onVisible - Optional callback invoked once when the observed element becomes visible.
+ * @returns A ref object to attach to the observed element (e.g. `<div ref={ref}>`).
+ *
+ * @example Lazy-load content when a section enters the viewport:
+ * ```tsx
+ * import { useVisibility } from "naystack/client";
+ *
+ * function LazySection() {
+ *   const [loaded, setLoaded] = useState(false);
+ *   const ref = useVisibility(() => setLoaded(true));
+ *
+ *   return (
+ *     <section ref={ref}>
+ *       {loaded ? <HeavyContent /> : <Placeholder />}
+ *     </section>
+ *   );
+ * }
+ * ```
+ *
+ * @example Trigger analytics when an element is seen:
+ * ```tsx
+ * const ref = useVisibility(() => trackImpression("hero-banner"));
+ * return <div ref={ref}>...</div>;
+ * ```
+ *
+ * @category Client
+ */
 declare function useVisibility(onVisible?: () => void): React.RefObject<null>;
+/**
+ * Returns whether a CSS media query currently matches. Useful for responsive behavior in JS.
+ *
+ * Returns `null` during SSR / before the first client-side check (to avoid hydration mismatches).
+ *
+ * @param query - A valid CSS media query string (e.g. `"(min-width: 768px)"`, `"(prefers-color-scheme: dark)"`).
+ * @returns `true` if the query matches, `false` if it doesn't, or `null` during SSR.
+ *
+ * @example Responsive navigation:
+ * ```tsx
+ * import { useBreakpoint } from "naystack/client";
+ *
+ * function ResponsiveNav() {
+ *   const isMobile = useBreakpoint("(max-width: 639px)");
+ *   if (isMobile === null) return <Skeleton />;  // SSR fallback
+ *   return isMobile ? <MobileNav /> : <DesktopNav />;
+ * }
+ * ```
+ *
+ * @example Detect user preferences:
+ * ```tsx
+ * const prefersReducedMotion = useBreakpoint("(prefers-reduced-motion: reduce)");
+ * ```
+ *
+ * @category Client
+ */
 declare function useBreakpoint(query: string): boolean | null;
 
 export { useBreakpoint, useVisibility };

package/dist/client/hooks.d.ts

@@ -1,6 +1,65 @@
 import * as React from 'react';
 
+/**
+ * Tracks when a DOM element enters the viewport and calls a callback.
+ * Uses `IntersectionObserver` with `rootMargin: "100px"` and `threshold: 0.1`.
+ *
+ * Attach the returned ref to the element you want to observe.
+ *
+ * @param onVisible - Optional callback invoked once when the observed element becomes visible.
+ * @returns A ref object to attach to the observed element (e.g. `<div ref={ref}>`).
+ *
+ * @example Lazy-load content when a section enters the viewport:
+ * ```tsx
+ * import { useVisibility } from "naystack/client";
+ *
+ * function LazySection() {
+ *   const [loaded, setLoaded] = useState(false);
+ *   const ref = useVisibility(() => setLoaded(true));
+ *
+ *   return (
+ *     <section ref={ref}>
+ *       {loaded ? <HeavyContent /> : <Placeholder />}
+ *     </section>
+ *   );
+ * }
+ * ```
+ *
+ * @example Trigger analytics when an element is seen:
+ * ```tsx
+ * const ref = useVisibility(() => trackImpression("hero-banner"));
+ * return <div ref={ref}>...</div>;
+ * ```
+ *
+ * @category Client
+ */
 declare function useVisibility(onVisible?: () => void): React.RefObject<null>;
+/**
+ * Returns whether a CSS media query currently matches. Useful for responsive behavior in JS.
+ *
+ * Returns `null` during SSR / before the first client-side check (to avoid hydration mismatches).
+ *
+ * @param query - A valid CSS media query string (e.g. `"(min-width: 768px)"`, `"(prefers-color-scheme: dark)"`).
+ * @returns `true` if the query matches, `false` if it doesn't, or `null` during SSR.
+ *
+ * @example Responsive navigation:
+ * ```tsx
+ * import { useBreakpoint } from "naystack/client";
+ *
+ * function ResponsiveNav() {
+ *   const isMobile = useBreakpoint("(max-width: 639px)");
+ *   if (isMobile === null) return <Skeleton />;  // SSR fallback
+ *   return isMobile ? <MobileNav /> : <DesktopNav />;
+ * }
+ * ```
+ *
+ * @example Detect user preferences:
+ * ```tsx
+ * const prefersReducedMotion = useBreakpoint("(prefers-reduced-motion: reduce)");
+ * ```
+ *
+ * @category Client
+ */
 declare function useBreakpoint(query: string): boolean | null;
 
 export { useBreakpoint, useVisibility };

package/dist/client/seo.d.mts

@@ -1,5 +1,51 @@
 import { Metadata } from 'next';
 
+/**
+ * Creates a metadata factory for Next.js pages. Call once with your site's default SEO config,
+ * then call the returned function per-page to generate the `Metadata` object.
+ *
+ * The returned function supports page-specific `title`, `description`, and `image` overrides.
+ * When a page title is provided, it's formatted as `"Page Title • Site Name"`.
+ *
+ * @param SEO - Base defaults for the whole site.
+ * @param SEO.title - Default document title (used when no page-specific title is provided).
+ * @param SEO.description - Default meta description.
+ * @param SEO.siteName - Application/site name (used in openGraph, twitter, and as the separator in titles).
+ * @param SEO.themeColor - Theme color for mobile browsers (e.g. `"#000000"`).
+ * @returns A function `(title?, description?, image?) => Metadata`. Pass page-specific overrides; they fill in or replace the defaults.
+ *
+ * @example Setup in a utility file:
+ * ```ts
+ * // lib/utils/seo.ts
+ * import { setupSEO } from "naystack/client";
+ *
+ * export const getSEO = setupSEO({
+ *   title: "Land Exchange Toolbox - Premium Real Estate Tools",
+ *   description: "Empower your real estate business with advanced tools.",
+ *   siteName: "Land Exchange Toolbox",
+ *   themeColor: "#5b9364",
+ * });
+ * ```
+ *
+ * @example Usage in a page:
+ * ```ts
+ * // app/dashboard/page.tsx
+ * import { getSEO } from "@/lib/utils/seo";
+ *
+ * export const metadata = getSEO("Dashboard", "Your personalized dashboard");
+ * // => title: "Dashboard • Land Exchange Toolbox", description: "Your personalized dashboard"
+ * ```
+ *
+ * @example Usage in generateMetadata:
+ * ```ts
+ * export async function generateMetadata({ params }) {
+ *   const deal = await getDeal(params.id);
+ *   return getSEO(deal.title, deal.description, deal.coverImage);
+ * }
+ * ```
+ *
+ * @category Client
+ */
 declare const setupSEO: (SEO: {
     title: string;
     description: string;

package/dist/client/seo.d.ts

@@ -1,5 +1,51 @@
 import { Metadata } from 'next';
 
+/**
+ * Creates a metadata factory for Next.js pages. Call once with your site's default SEO config,
+ * then call the returned function per-page to generate the `Metadata` object.
+ *
+ * The returned function supports page-specific `title`, `description`, and `image` overrides.
+ * When a page title is provided, it's formatted as `"Page Title • Site Name"`.
+ *
+ * @param SEO - Base defaults for the whole site.
+ * @param SEO.title - Default document title (used when no page-specific title is provided).
+ * @param SEO.description - Default meta description.
+ * @param SEO.siteName - Application/site name (used in openGraph, twitter, and as the separator in titles).
+ * @param SEO.themeColor - Theme color for mobile browsers (e.g. `"#000000"`).
+ * @returns A function `(title?, description?, image?) => Metadata`. Pass page-specific overrides; they fill in or replace the defaults.
+ *
+ * @example Setup in a utility file:
+ * ```ts
+ * // lib/utils/seo.ts
+ * import { setupSEO } from "naystack/client";
+ *
+ * export const getSEO = setupSEO({
+ *   title: "Land Exchange Toolbox - Premium Real Estate Tools",
+ *   description: "Empower your real estate business with advanced tools.",
+ *   siteName: "Land Exchange Toolbox",
+ *   themeColor: "#5b9364",
+ * });
+ * ```
+ *
+ * @example Usage in a page:
+ * ```ts
+ * // app/dashboard/page.tsx
+ * import { getSEO } from "@/lib/utils/seo";
+ *
+ * export const metadata = getSEO("Dashboard", "Your personalized dashboard");
+ * // => title: "Dashboard • Land Exchange Toolbox", description: "Your personalized dashboard"
+ * ```
+ *
+ * @example Usage in generateMetadata:
+ * ```ts
+ * export async function generateMetadata({ params }) {
+ *   const deal = await getDeal(params.id);
+ *   return getSEO(deal.title, deal.description, deal.coverImage);
+ * }
+ * ```
+ *
+ * @category Client
+ */
 declare const setupSEO: (SEO: {
     title: string;
     description: string;