naystack 1.5.8 → 1.5.10

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;

package/dist/env.d.mts

@@ -1,24 +1,85 @@
+/**
+ * Enum of all environment variable keys used by the naystack stack.
+ * Use with {@link getEnv} or {@link getEnvValue} to read these variables.
+ *
+ * @category Environment
+ */
 declare enum EnvVariable {
+    /** GraphQL endpoint URL (client-side, e.g. `/api/graphql`). */
     NEXT_PUBLIC_GRAPHQL_ENDPOINT = "NEXT_PUBLIC_GRAPHQL_ENDPOINT",
+    /** Email auth endpoint URL (client-side, e.g. `/api/email`). */
     NEXT_PUBLIC_EMAIL_AUTH_ENDPOINT = "NEXT_PUBLIC_EMAIL_AUTH_ENDPOINT",
+    /** Google OAuth endpoint URL (client-side, e.g. `/api/google`). */
     NEXT_PUBLIC_GOOGLE_AUTH_ENDPOINT = "NEXT_PUBLIC_GOOGLE_AUTH_ENDPOINT",
+    /** Instagram OAuth endpoint URL (client-side, e.g. `/api/instagram`). */
     NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT = "NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT",
+    /** File upload endpoint URL (client-side, e.g. `/api/file`). */
     NEXT_PUBLIC_FILE_ENDPOINT = "NEXT_PUBLIC_FILE_ENDPOINT",
+    /** Base URL of the app (e.g. `https://yourapp.com`). Used for SEO and Apple Web App metadata. */
     NEXT_PUBLIC_BASE_URL = "NEXT_PUBLIC_BASE_URL",
+    /** Secret key for signing JWT refresh tokens. */
     REFRESH_KEY = "REFRESH_KEY",
+    /** Secret key for signing JWT access tokens. */
     SIGNING_KEY = "SIGNING_KEY",
+    /** Instagram app client secret (from Meta Developer Portal). */
     INSTAGRAM_CLIENT_SECRET = "INSTAGRAM_CLIENT_SECRET",
+    /** Instagram app client id (from Meta Developer Portal). */
     INSTAGRAM_CLIENT_ID = "INSTAGRAM_CLIENT_ID",
+    /** Google OAuth client secret (from Google Cloud Console). */
     GOOGLE_CLIENT_SECRET = "GOOGLE_CLIENT_SECRET",
+    /** Google OAuth client id (from Google Cloud Console). */
     GOOGLE_CLIENT_ID = "GOOGLE_CLIENT_ID",
+    /** Cloudflare Turnstile secret key (optional — enables captcha on auth routes). */
     TURNSTILE_KEY = "TURNSTILE_KEY",
+    /** AWS access key id for S3. */
     AWS_ACCESS_KEY_ID = "AWS_ACCESS_KEY_ID",
+    /** AWS secret access key for S3. */
     AWS_ACCESS_KEY_SECRET = "AWS_ACCESS_KEY_SECRET",
+    /** AWS region for S3 (e.g. `us-east-1`). */
     AWS_REGION = "AWS_REGION",
+    /** AWS S3 bucket name. */
     AWS_BUCKET = "AWS_BUCKET",
+    /** Node environment (`development`, `production`, etc.). Used for Apollo landing page and introspection. */
     NODE_ENV = "NODE_ENV"
 }
+/**
+ * Reads an environment variable by key. Does **not** throw if the value is missing.
+ *
+ * @param key - One of the {@link EnvVariable} enum values.
+ * @returns The value of the env var, or `undefined` if unset.
+ *
+ * @example
+ * ```ts
+ * import { getEnvValue, EnvVariable } from "naystack/env";
+ *
+ * const region = getEnvValue(EnvVariable.AWS_REGION); // "us-east-1" or undefined
+ * ```
+ *
+ * @category Environment
+ */
 declare const getEnvValue: (key: EnvVariable) => string | undefined;
+/**
+ * Reads an environment variable and **throws** if it's missing (unless `skipCheck` is `true`).
+ * Use this for required configuration values.
+ *
+ * @param key - One of the {@link EnvVariable} enum values.
+ * @param skipCheck - If `true`, the function does **not** throw when the value is missing and returns `string | undefined`.
+ *   Useful for optional vars (e.g. `getEnv(EnvVariable.TURNSTILE_KEY, true)`).
+ * @returns The env value. When `skipCheck` is `true`, the type is `string | undefined`; otherwise `string` (throws before returning if missing).
+ *
+ * @example
+ * ```ts
+ * import { getEnv, EnvVariable } from "naystack/env";
+ *
+ * // Required — throws if missing:
+ * const signingKey = getEnv(EnvVariable.SIGNING_KEY);
+ *
+ * // Optional — returns undefined if missing:
+ * const turnstile = getEnv(EnvVariable.TURNSTILE_KEY, true);
+ * ```
+ *
+ * @category Environment
+ */
 declare function getEnv<T extends boolean = false>(key: EnvVariable, skipCheck?: T): T extends true ? string | undefined : string;
 
 export { EnvVariable, getEnv, getEnvValue };