naystack 1.5.8 → 1.5.10

package/dist/env.d.ts

@@ -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 };

package/dist/file/client.d.mts

@@ -1,7 +1,59 @@
+/**
+ * Returns a function that uploads a file to your file upload endpoint with the current auth token.
+ * Must be used inside a tree that provides the token (i.e. inside `AuthWrapper`).
+ *
+ * The endpoint is read from `NEXT_PUBLIC_FILE_ENDPOINT` env var. The file is sent as multipart form data
+ * along with a `type` string and optional JSON `data` for metadata.
+ *
+ * @returns A function `(file, type, data?) => Promise<FileUploadResponseType | null>`.
+ *   - `file` — `File` or `Blob` to upload.
+ *   - `type` — String category (e.g. `"avatar"`, `"DealDocument"`); sent as form field `type`.
+ *   - `data` — Optional JSON-serializable object for metadata; sent as form field `data`.
+ *   Resolves to the JSON response `{ url, onUploadResponse }` or `null`.
+ *
+ * @example
+ * ```tsx
+ * import { useFileUpload } from "naystack/file/client";
+ *
+ * function FileUploader({ dealId }: { dealId: number }) {
+ *   const uploadFile = useFileUpload();
+ *   const [uploading, setUploading] = useState(false);
+ *
+ *   const handleUpload = async (file: File) => {
+ *     setUploading(true);
+ *     try {
+ *       const result = await uploadFile(file, "DealDocument", {
+ *         dealId,
+ *         fileName: file.name,
+ *         category: "Contract",
+ *       });
+ *       if (result?.url) {
+ *         console.log("Uploaded:", result.url);
+ *         router.refresh();
+ *       }
+ *     } finally {
+ *       setUploading(false);
+ *     }
+ *   };
+ *
+ *   return <input type="file" onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])} />;
+ * }
+ * ```
+ *
+ * @category File
+ */
 declare const useFileUpload: () => (file: File | Blob, type: string, data?: object) => Promise<FileUploadResponseType>;
+/**
+ * Shape of the JSON response from the file upload PUT endpoint.
+ *
+ * @property url - The public S3 URL of the uploaded file.
+ * @property onUploadResponse - The return value from the `onUpload` callback in `setupFileUpload`.
+ *
+ * @category File
+ */
 interface FileUploadResponseType {
     url?: string;
     onUploadResponse?: object;
 }
 
-export { useFileUpload };
+export { type FileUploadResponseType, useFileUpload };

package/dist/file/client.d.ts

@@ -1,7 +1,59 @@
+/**
+ * Returns a function that uploads a file to your file upload endpoint with the current auth token.
+ * Must be used inside a tree that provides the token (i.e. inside `AuthWrapper`).
+ *
+ * The endpoint is read from `NEXT_PUBLIC_FILE_ENDPOINT` env var. The file is sent as multipart form data
+ * along with a `type` string and optional JSON `data` for metadata.
+ *
+ * @returns A function `(file, type, data?) => Promise<FileUploadResponseType | null>`.
+ *   - `file` — `File` or `Blob` to upload.
+ *   - `type` — String category (e.g. `"avatar"`, `"DealDocument"`); sent as form field `type`.
+ *   - `data` — Optional JSON-serializable object for metadata; sent as form field `data`.
+ *   Resolves to the JSON response `{ url, onUploadResponse }` or `null`.
+ *
+ * @example
+ * ```tsx
+ * import { useFileUpload } from "naystack/file/client";
+ *
+ * function FileUploader({ dealId }: { dealId: number }) {
+ *   const uploadFile = useFileUpload();
+ *   const [uploading, setUploading] = useState(false);
+ *
+ *   const handleUpload = async (file: File) => {
+ *     setUploading(true);
+ *     try {
+ *       const result = await uploadFile(file, "DealDocument", {
+ *         dealId,
+ *         fileName: file.name,
+ *         category: "Contract",
+ *       });
+ *       if (result?.url) {
+ *         console.log("Uploaded:", result.url);
+ *         router.refresh();
+ *       }
+ *     } finally {
+ *       setUploading(false);
+ *     }
+ *   };
+ *
+ *   return <input type="file" onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])} />;
+ * }
+ * ```
+ *
+ * @category File
+ */
 declare const useFileUpload: () => (file: File | Blob, type: string, data?: object) => Promise<FileUploadResponseType>;
+/**
+ * Shape of the JSON response from the file upload PUT endpoint.
+ *
+ * @property url - The public S3 URL of the uploaded file.
+ * @property onUploadResponse - The return value from the `onUpload` callback in `setupFileUpload`.
+ *
+ * @category File
+ */
 interface FileUploadResponseType {
     url?: string;
     onUploadResponse?: object;
 }
 
-export { useFileUpload };
+export { type FileUploadResponseType, useFileUpload };

package/dist/file/index.cjs.js

@@ -30,7 +30,6 @@ var import_uuid = require("uuid");
 
 // src/auth/email/utils.ts
 var import_jsonwebtoken2 = require("jsonwebtoken");
-var import_headers2 = require("next/headers");
 
 // src/auth/email/token.ts
 var import_bcryptjs = require("bcryptjs");

package/dist/file/index.esm.js

@@ -4,7 +4,6 @@ import { v4 } from "uuid";
 
 // src/auth/email/utils.ts
 import { verify as verify2 } from "jsonwebtoken";
-import { cookies as cookies2 } from "next/headers";
 
 // src/auth/email/token.ts
 import { compare } from "bcryptjs";

package/dist/file/put.cjs.js

@@ -28,7 +28,6 @@ var import_uuid = require("uuid");
 
 // src/auth/email/utils.ts
 var import_jsonwebtoken2 = require("jsonwebtoken");
-var import_headers2 = require("next/headers");
 
 // src/auth/email/token.ts
 var import_bcryptjs = require("bcryptjs");

package/dist/file/put.d.mts

@@ -2,6 +2,17 @@ import { S3Client } from '@aws-sdk/client-s3';
 import { NextRequest, NextResponse } from 'next/server';
 import { SetupFileUploadOptions } from './setup.mjs';
 
+/**
+ * Returns the PUT route handler for file upload.
+ *
+ * Requires authentication (Bearer token, not refresh cookie).
+ * Expects multipart form data with fields: `file` (File), `type` (string), and optional `data` (JSON string).
+ *
+ * @param options - `SetupFileUploadOptions` (getKey, onUpload).
+ * @param client - S3 client instance.
+ * @returns Async Next.js route handler for PUT requests.
+ * @category File
+ */
 declare const getFileUploadPutRoute: (options: SetupFileUploadOptions, client: S3Client) => (req: NextRequest) => Promise<NextResponse<{
     error: string;
 }> | NextResponse<{

package/dist/file/put.d.ts

@@ -2,6 +2,17 @@ import { S3Client } from '@aws-sdk/client-s3';
 import { NextRequest, NextResponse } from 'next/server';
 import { SetupFileUploadOptions } from './setup.js';
 
+/**
+ * Returns the PUT route handler for file upload.
+ *
+ * Requires authentication (Bearer token, not refresh cookie).
+ * Expects multipart form data with fields: `file` (File), `type` (string), and optional `data` (JSON string).
+ *
+ * @param options - `SetupFileUploadOptions` (getKey, onUpload).
+ * @param client - S3 client instance.
+ * @returns Async Next.js route handler for PUT requests.
+ * @category File
+ */
 declare const getFileUploadPutRoute: (options: SetupFileUploadOptions, client: S3Client) => (req: NextRequest) => Promise<NextResponse<{
     error: string;
 }> | NextResponse<{

package/dist/file/put.esm.js

@@ -4,7 +4,6 @@ import { v4 } from "uuid";
 
 // src/auth/email/utils.ts
 import { verify as verify2 } from "jsonwebtoken";
-import { cookies as cookies2 } from "next/headers";
 
 // src/auth/email/token.ts
 import { compare } from "bcryptjs";

package/dist/file/setup.cjs.js

@@ -30,7 +30,6 @@ var import_uuid = require("uuid");
 
 // src/auth/email/utils.ts
 var import_jsonwebtoken2 = require("jsonwebtoken");
-var import_headers2 = require("next/headers");
 
 // src/auth/email/token.ts
 var import_bcryptjs = require("bcryptjs");

package/dist/file/setup.d.mts

@@ -1,5 +1,14 @@
 import * as next_server from 'next/server';
 
+/**
+ * Options for setting up file upload via {@link setupFileUpload}.
+ *
+ * @property getKey - Optional. Given `{ type, userId, data }`, returns the S3 object key for the upload. If omitted, a UUID is generated.
+ * @property onUpload - **Required.** Called after each successful upload with `{ url, type, userId, data }`.
+ *   The return value is included in the API response as `onUploadResponse` (e.g. save metadata to your database and return it).
+ *
+ * @category File
+ */
 interface SetupFileUploadOptions {
     getKey?: (data: {
         type: string;
@@ -13,6 +22,45 @@ interface SetupFileUploadOptions {
         data: object;
     }) => Promise<object>;
 }
+/**
+ * Configures file upload for S3. Returns a `PUT` route handler (for the client to upload files) and server-side helpers.
+ *
+ * Mount the `PUT` handler on your file upload API route (e.g. `app/api/(rest)/file/route.ts`).
+ * The client can then use `useFileUpload()` from `naystack/file/client` to upload files with the auth token.
+ *
+ * AWS credentials are read from env vars: `AWS_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_SECRET`, `AWS_REGION`, `AWS_BUCKET`.
+ *
+ * @param options - Configuration. See {@link SetupFileUploadOptions}.
+ * @returns Object with:
+ *   - `PUT` — Next.js route handler for file uploads (auth required, multipart form).
+ *   - `uploadFile(keys, { url?, blob? })` — Server-side: upload a file from URL or Blob to S3.
+ *   - `deleteFile(url)` — Server-side: delete a file by its S3 URL.
+ *   - `getUploadURL(keys)` — Server-side: get a presigned PUT URL (5-minute expiry).
+ *   - `getDownloadURL(keys)` — Get the public download URL for a key.
+ *
+ * @example
+ * ```ts
+ * // app/api/(rest)/file/route.ts
+ * import { setupFileUpload } from "naystack/file";
+ *
+ * export const { PUT } = setupFileUpload({
+ *   onUpload: async ({ url, type, userId, data }) => {
+ *     if (type === "DealDocument" && url) {
+ *       const payload = data as { dealId: number; fileName: string };
+ *       const [row] = await db.insert(DocumentsTable).values({
+ *         dealId: payload.dealId, fileURL: url, fileName: payload.fileName,
+ *       }).returning();
+ *       return row ?? {};
+ *     }
+ *     return {};
+ *   },
+ *   // Optional: customize the S3 key (defaults to UUID)
+ *   getKey: async ({ type, userId }) => `${type}/${userId}/${crypto.randomUUID()}`,
+ * });
+ * ```
+ *
+ * @category File
+ */
 declare function setupFileUpload(options: SetupFileUploadOptions): {
     PUT: (req: next_server.NextRequest) => Promise<next_server.NextResponse<{
         error: string;

package/dist/file/setup.d.ts

@@ -1,5 +1,14 @@
 import * as next_server from 'next/server';
 
+/**
+ * Options for setting up file upload via {@link setupFileUpload}.
+ *
+ * @property getKey - Optional. Given `{ type, userId, data }`, returns the S3 object key for the upload. If omitted, a UUID is generated.
+ * @property onUpload - **Required.** Called after each successful upload with `{ url, type, userId, data }`.
+ *   The return value is included in the API response as `onUploadResponse` (e.g. save metadata to your database and return it).
+ *
+ * @category File
+ */
 interface SetupFileUploadOptions {
     getKey?: (data: {
         type: string;
@@ -13,6 +22,45 @@ interface SetupFileUploadOptions {
         data: object;
     }) => Promise<object>;
 }
+/**
+ * Configures file upload for S3. Returns a `PUT` route handler (for the client to upload files) and server-side helpers.
+ *
+ * Mount the `PUT` handler on your file upload API route (e.g. `app/api/(rest)/file/route.ts`).
+ * The client can then use `useFileUpload()` from `naystack/file/client` to upload files with the auth token.
+ *
+ * AWS credentials are read from env vars: `AWS_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_SECRET`, `AWS_REGION`, `AWS_BUCKET`.
+ *
+ * @param options - Configuration. See {@link SetupFileUploadOptions}.
+ * @returns Object with:
+ *   - `PUT` — Next.js route handler for file uploads (auth required, multipart form).
+ *   - `uploadFile(keys, { url?, blob? })` — Server-side: upload a file from URL or Blob to S3.
+ *   - `deleteFile(url)` — Server-side: delete a file by its S3 URL.
+ *   - `getUploadURL(keys)` — Server-side: get a presigned PUT URL (5-minute expiry).
+ *   - `getDownloadURL(keys)` — Get the public download URL for a key.
+ *
+ * @example
+ * ```ts
+ * // app/api/(rest)/file/route.ts
+ * import { setupFileUpload } from "naystack/file";
+ *
+ * export const { PUT } = setupFileUpload({
+ *   onUpload: async ({ url, type, userId, data }) => {
+ *     if (type === "DealDocument" && url) {
+ *       const payload = data as { dealId: number; fileName: string };
+ *       const [row] = await db.insert(DocumentsTable).values({
+ *         dealId: payload.dealId, fileURL: url, fileName: payload.fileName,
+ *       }).returning();
+ *       return row ?? {};
+ *     }
+ *     return {};
+ *   },
+ *   // Optional: customize the S3 key (defaults to UUID)
+ *   getKey: async ({ type, userId }) => `${type}/${userId}/${crypto.randomUUID()}`,
+ * });
+ * ```
+ *
+ * @category File
+ */
 declare function setupFileUpload(options: SetupFileUploadOptions): {
     PUT: (req: next_server.NextRequest) => Promise<next_server.NextResponse<{
         error: string;

package/dist/file/setup.esm.js

@@ -4,7 +4,6 @@ import { v4 } from "uuid";
 
 // src/auth/email/utils.ts
 import { verify as verify2 } from "jsonwebtoken";
-import { cookies as cookies2 } from "next/headers";
 
 // src/auth/email/token.ts
 import { compare } from "bcryptjs";

package/dist/file/utils.d.mts

@@ -1,14 +1,55 @@
 import * as _aws_sdk_client_s3 from '@aws-sdk/client-s3';
 import { S3Client } from '@aws-sdk/client-s3';
 
+/**
+ * Creates an S3 client using env credentials (`AWS_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_SECRET`, `AWS_REGION`).
+ * @returns Configured `S3Client` instance.
+ * @category File
+ */
 declare const getS3Client: () => S3Client;
+/**
+ * Returns a function that generates a presigned PUT URL for uploading to the given S3 key(s).
+ * The presigned URL expires after 5 minutes.
+ *
+ * @param client - S3 client instance.
+ * @returns `(keys: string | string[]) => Promise<string>` — the presigned upload URL.
+ * @category File
+ */
 declare const getUploadURL: (client: S3Client) => (keys: string | string[]) => Promise<string>;
+/**
+ * Builds the public download URL for one or more keys in the configured S3 bucket.
+ *
+ * @param keys - S3 key or key path segments (array joined by `/`).
+ * @returns Full HTTPS URL for the object.
+ * @category File
+ */
 declare const getDownloadURL: (keys: string | string[]) => string;
+/**
+ * Returns a function that uploads a file (by URL or Blob) to the given S3 key(s).
+ *
+ * @param client - S3 client instance.
+ * @returns `(keys, { url?, blob? }) => Promise<string | null>` — the download URL on success, or `null` if no input.
+ * @category File
+ */
 declare const uploadFile: (client: S3Client) => (keys: string | string[], { url, blob, }: {
     blob?: Blob;
     url?: string;
 }) => Promise<string | null>;
+/**
+ * Returns a function that deletes an S3 object by its full URL.
+ *
+ * @param client - S3 client instance.
+ * @returns `(url: string) => Promise<boolean>` — `true` if deleted successfully, `false` otherwise.
+ * @category File
+ */
 declare const deleteFile: (client: S3Client) => (url: string) => Promise<boolean>;
+/**
+ * Returns a function that uploads a Blob/File to S3 at the given key.
+ *
+ * @param client - S3 client instance.
+ * @returns `(file: File | Blob, key: string) => Promise<PutObjectCommandOutput>`.
+ * @category File
+ */
 declare const uploadBlob: (client: S3Client) => (file: File | Blob, key: string) => Promise<_aws_sdk_client_s3.PutObjectCommandOutput>;
 
 export { deleteFile, getDownloadURL, getS3Client, getUploadURL, uploadBlob, uploadFile };

package/dist/file/utils.d.ts

@@ -1,14 +1,55 @@
 import * as _aws_sdk_client_s3 from '@aws-sdk/client-s3';
 import { S3Client } from '@aws-sdk/client-s3';
 
+/**
+ * Creates an S3 client using env credentials (`AWS_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_SECRET`, `AWS_REGION`).
+ * @returns Configured `S3Client` instance.
+ * @category File
+ */
 declare const getS3Client: () => S3Client;
+/**
+ * Returns a function that generates a presigned PUT URL for uploading to the given S3 key(s).
+ * The presigned URL expires after 5 minutes.
+ *
+ * @param client - S3 client instance.
+ * @returns `(keys: string | string[]) => Promise<string>` — the presigned upload URL.
+ * @category File
+ */
 declare const getUploadURL: (client: S3Client) => (keys: string | string[]) => Promise<string>;
+/**
+ * Builds the public download URL for one or more keys in the configured S3 bucket.
+ *
+ * @param keys - S3 key or key path segments (array joined by `/`).
+ * @returns Full HTTPS URL for the object.
+ * @category File
+ */
 declare const getDownloadURL: (keys: string | string[]) => string;
+/**
+ * Returns a function that uploads a file (by URL or Blob) to the given S3 key(s).
+ *
+ * @param client - S3 client instance.
+ * @returns `(keys, { url?, blob? }) => Promise<string | null>` — the download URL on success, or `null` if no input.
+ * @category File
+ */
 declare const uploadFile: (client: S3Client) => (keys: string | string[], { url, blob, }: {
     blob?: Blob;
     url?: string;
 }) => Promise<string | null>;
+/**
+ * Returns a function that deletes an S3 object by its full URL.
+ *
+ * @param client - S3 client instance.
+ * @returns `(url: string) => Promise<boolean>` — `true` if deleted successfully, `false` otherwise.
+ * @category File
+ */
 declare const deleteFile: (client: S3Client) => (url: string) => Promise<boolean>;
+/**
+ * Returns a function that uploads a Blob/File to S3 at the given key.
+ *
+ * @param client - S3 client instance.
+ * @returns `(file: File | Blob, key: string) => Promise<PutObjectCommandOutput>`.
+ * @category File
+ */
 declare const uploadBlob: (client: S3Client) => (file: File | Blob, key: string) => Promise<_aws_sdk_client_s3.PutObjectCommandOutput>;
 
 export { deleteFile, getDownloadURL, getS3Client, getUploadURL, uploadBlob, uploadFile };

package/dist/graphql/client.d.mts

@@ -3,16 +3,129 @@ import { InMemoryCacheConfig, OperationVariables, MutationHookOptions } from '@a
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import React__default, { PropsWithChildren } from 'react';
 
+/**
+ * Apollo Client provider for Next.js. Wrap your app (or a subtree) so client components can run GraphQL queries and mutations.
+ * The GraphQL endpoint is read from `NEXT_PUBLIC_GRAPHQL_ENDPOINT` env var.
+ *
+ * Must be placed **inside** `AuthWrapper` (since `useAuthQuery` / `useAuthMutation` depend on the auth token).
+ *
+ * @param props - Component props.
+ * @param props.children - React children (your app or page content).
+ * @param props.cacheConfig - Optional `InMemoryCache` config (e.g. `typePolicies`, `addTypename`). Passed to Apollo's `InMemoryCache`.
+ * @returns Provider component that supplies Apollo Client to the tree.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { AuthWrapper } from "naystack/auth/email/client";
+ * import { ApolloWrapper } from "naystack/graphql/client";
+ *
+ * export default function RootLayout({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <html lang="en">
+ *       <body>
+ *         <AuthWrapper>
+ *           <ApolloWrapper>{children}</ApolloWrapper>
+ *         </AuthWrapper>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * @category GraphQL
+ */
 declare const ApolloWrapper: ({ children, cacheConfig, }: PropsWithChildren<{
     cacheConfig?: InMemoryCacheConfig;
 }>) => React__default.JSX.Element;
+/**
+ * Builds the Apollo link context so requests include the user's Bearer token.
+ * Used internally by `useAuthQuery` / `useAuthMutation`; you typically don't call this directly.
+ *
+ * @param token - The JWT access token. If `null`/`undefined`, returns `undefined` (no auth header).
+ * @returns Context object with `headers.authorization` and `credentials: 'omit'`, or `undefined` if no token.
+ *
+ * @category GraphQL
+ */
 declare const tokenContext: (token?: string | null) => {
     headers: {
         authorization: string;
     };
     credentials: string;
 } | undefined;
+/**
+ * Hook to run a GraphQL query with the current user's token. The query auto-fires when both the token
+ * and variables are available. Returns a refetch function and the Apollo query result.
+ *
+ * Uses `fetchPolicy: "no-cache"` by default to always get fresh data.
+ *
+ * @param query - A `TypedDocumentNode` for the query (e.g. from codegen or a `gql` template).
+ * @param variables - Optional initial variables. Query fires automatically when this and token are set; change to refetch.
+ * @returns Tuple: `[refetch, result]`.
+ *   - `refetch(input)` — runs the query again with the given input (passed as `variables.input`).
+ *   - `result` — `{ data, loading, error }` from Apollo.
+ *
+ * @example Lazy query (no initial variables, manually triggered):
+ * ```tsx
+ * import { useAuthQuery } from "naystack/graphql/client";
+ * import { GET_SUMMARY } from "@/constants/graphql/queries";
+ *
+ * function SummaryCard({ type }: { type: string }) {
+ *   const [getSummary, { loading, data }] = useAuthQuery(GET_SUMMARY);
+ *
+ *   const handleFetch = async () => {
+ *     const result = await getSummary({ type });
+ *     if (result.data?.getSummary) setSummary(result.data.getSummary);
+ *   };
+ *
+ *   return <button onClick={handleFetch} disabled={loading}>Get Summary</button>;
+ * }
+ * ```
+ *
+ * @example Auto-firing query with variables:
+ * ```tsx
+ * const [refetch, { data, loading }] = useAuthQuery(GET_ORGANIZATION_DETAILS, { id: orgId });
+ * // Query fires automatically when orgId and token are available
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function useAuthQuery<T, V extends OperationVariables>(query: TypedDocumentNode<T, V>, variables?: V): readonly [(input: V["input"]) => Promise<_apollo_client.QueryResult<T, V>>, _apollo_client.QueryResult<T, V>];
+/**
+ * Hook to run a GraphQL mutation with the current user's token. Returns a function you call with the mutation input.
+ *
+ * The input is sent as `variables.input` to the GraphQL endpoint.
+ *
+ * @param mutation - A `TypedDocumentNode` for the mutation (e.g. from codegen or a `gql` template).
+ * @param options - Optional Apollo `MutationHookOptions` (e.g. `onCompleted`, `onError`, `refetchQueries`).
+ * @returns Tuple: `[mutate, result]`.
+ *   - `mutate(input)` — runs the mutation with the given input. Returns a Promise with `{ data }`.
+ *   - `result` — `{ data, loading, error }` from Apollo.
+ *
+ * @example
+ * ```tsx
+ * import { useAuthMutation } from "naystack/graphql/client";
+ * import { CREATE_DEAL } from "@/lib/gql/mutations";
+ *
+ * function CreateDealModal({ propertyId }: { propertyId: number }) {
+ *   const [createDeal, { loading }] = useAuthMutation(CREATE_DEAL);
+ *
+ *   const onSubmit = async (values: FormFields) => {
+ *     const response = await createDeal({
+ *       propertyId,
+ *       share: Number(values.share),
+ *       targetProfit: Number(values.targetProfit),
+ *     });
+ *     const dealId = response.data?.createDeal;
+ *     if (dealId) router.push(`/deals/${dealId}`);
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit(onSubmit)}>...</form>;
+ * }
+ * ```
+ *
+ * @category GraphQL
+ */
 declare function useAuthMutation<T, V extends OperationVariables>(mutation: TypedDocumentNode<T, V>, options?: MutationHookOptions<T, V>): readonly [(input: V["input"]) => Promise<_apollo_client.FetchResult<T>>, _apollo_client.MutationResult<T>];
 
 export { ApolloWrapper, tokenContext, useAuthMutation, useAuthQuery };