@btst/stack 1.1.10 → 1.2.0

package/README.md

@@ -30,21 +30,6 @@ Better Stack lets you **add these features in minutes** as composable plugins th
 - **Lifecycle hooks** - Intercept at any point: authorization, data transformation, analytics, caching, webhooks
 - **Horizontal features** - Perfect for blog, scheduling, feedback, newsletters, AI assistants, comments—anything reusable across apps
 
-## What Can You Add?
-
-**Blog** - Content management, editor, drafts, publishing, SEO, RSS feeds
-
-**Scheduling** - Calendar views, time slot booking, availability management, reminders
-
-**Feedback** - In-app feedback widgets, user surveys, bug reporting, feature requests
-
-**Newsletters** - Subscriber management, email campaigns, unsubscribe handling, analytics
-
-**AI Assistant** - Chat interfaces, prompt templates, conversation history, streaming responses
-
-**Comments** - Threaded discussions, moderation, reactions, notifications
-
-And any other horizontal feature your app needs. Each comes with a complete UI, backend, and data layer.
 
 ## Installation
 
@@ -60,165 +45,15 @@ npm install -D @btst/cli
 
 The CLI helps generate migrations, Prisma schemas, and other database artifacts from your plugin schemas.
 
-## Quick Example: Add a Blog to Next.js
-
-### 1. Backend API (`lib/better-stack.ts`)
-
-```ts
-import { betterStack } from "@btst/stack"
-import { blogBackendPlugin } from "@btst/stack/plugins/blog/api"
-import { createPrismaAdapter } from "@btst/adapter-prisma"
-
-const { handler, dbSchema } = betterStack({
-  basePath: "/api/data",
-  plugins: {
-    blog: blogBackendPlugin()
-  },
-  adapter: (db) => createPrismaAdapter(db)({})
-})
-
-export { handler, dbSchema }
-```
-
-**Note:** `betterStack()` returns both `handler` and `dbSchema`. The `dbSchema` contains all merged database schemas from your plugins. Use [@btst/cli](https://www.npmjs.com/package/@btst/cli) to generate migrations, Prisma schemas, or other database artifacts from your `dbSchema`.
-
-For example, to generate a Prisma schema from your `dbSchema`:
-
-```bash
-npx @btst/cli generate --orm prisma --config lib/better-db.ts --output prisma/schema.prisma --filter-auth
-```
-
-This reads your `dbSchema` export and generates the corresponding Prisma schema file.
-
-### 2. API Route (`app/api/[[...]]/route.ts`)
-
-```ts
-import { handler } from "@/lib/better-stack"
-
-export const GET = handler
-export const POST = handler
-```
-
-### 3. Client Setup (`lib/better-stack-client.tsx`)
-
-```ts
-import { createStackClient } from "@btst/stack/client"
-import { blogClientPlugin } from "@btst/stack/plugins/blog/client"
-
-export const getStackClient = (queryClient: QueryClient) => {
-  return createStackClient({
-    plugins: {
-      blog: blogClientPlugin({
-        queryClient,
-        apiBaseURL: baseURL,
-        apiBasePath: "/api/data",
-        siteBaseURL: baseURL,
-        siteBasePath: "/pages"
-      })
-    }
-  })
-}
-```
-
-### 4. Page Handler (`app/pages/[[...all]]/page.tsx`)
-
-```ts
-export default async function Page({ params }) {
-  const path = `/${(await params).all?.join("/") || ""}`
-  const stackClient = getStackClient(queryClient)
-  const route = stackClient.router.getRoute(path)
-  
-  if (route?.loader) await route.loader()
-  
-  return (
-    <HydrationBoundary state={dehydrate(queryClient)}>
-      <ClientRouteResolver path={path} />
-    </HydrationBoundary>
-  )
-}
-```
-
-### 5. Layout Provider (`app/pages/[[...all]]/layout.tsx`)
-
-```ts
-import { BetterStackProvider } from "@btst/stack/context"
-import Link from "next/link"
-import Image from "next/image"
-import { useRouter } from "next/navigation"
-
-export default function Layout({ children }) {
-  const router = useRouter()
-  
-  return (
-    <BetterStackProvider
-      basePath="/pages"
-      overrides={{
-        blog: {
-          // Use Next.js optimized Image component
-          Image: (props) => (
-            <Image
-              alt={props.alt || ""}
-              src={props.src || ""}
-              width={400}
-              height={300}
-            />
-          ),
-          // Use Next.js Link for client-side navigation
-          navigate: (path) => router.push(path),
-          refresh: () => router.refresh()
-        }
-      }}
-    >
-      {children}
-    </BetterStackProvider>
-  )
-}
-```
-
-### 6. Sitemap Generation (`app/sitemap.ts`)
-
-```ts
-import type { MetadataRoute } from "next"
-import { QueryClient } from "@tanstack/react-query"
-import { getStackClient } from "@/lib/better-stack-client"
-
-export const dynamic = "force-dynamic"
-
-export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
-  const queryClient = new QueryClient()
-  const stackClient = getStackClient(queryClient)
-  const entries = await stackClient.generateSitemap()
-
-  return entries.map((e) => ({
-    url: e.url,
-    lastModified: e.lastModified,
-    changeFrequency: e.changeFrequency,
-    priority: e.priority,
-  }))
-}
-```
-
-**That's it.** Your blog feature is live with:
-- ✅ `/blog` - Post listing page
-- ✅ `/blog/[slug]` - Individual post pages  
-- ✅ `/blog/new` - Create post editor
-- ✅ `/blog/[slug]/edit` - Edit post page
-- ✅ Full CRUD API (`/api/data/blog/*`)
-- ✅ Server-side rendering
-- ✅ Automatic metadata generation
-- ✅ Automatic sitemap generation
-- ✅ React Query hooks (`usePosts`, `usePost`, etc.)
-
-Now add scheduling, feedback, or newsletters the same way. Each feature is independent and composable.
+Learn more about Better Stack, full installation, usage instructions and available plugins in the [documentation](https://www.better-stack.ai/docs).
 
 ## The Bigger Picture
 
 Better Stack transforms how you think about building apps:
 
 - **Open source** - Share complete features, not just code snippets. Someone can add a newsletter plugin to their Next.js app in minutes
-- **Fast development** - Add 5 features in an afternoon instead of 5 weeks. Validate ideas faster
-- **Agencies** - Create a library of reusable features. Drop scheduling into client A's app, feedback into client B's app.
-- **SaaS platforms** - Offer feature plugins your customers can compose. They pick blog + scheduling + AI assistant, mix and match to build their ideal app
+- **Fast development** - Add 5 features in an afternoon instead of 5 months. Validate ideas faster
+- **Framework and Database Agnostic** - Use any framework and database you want. Better Stack works with any modern framework and database.
 
 
 Each plugin is a complete, self-contained horizontal full-stack feature. No framework lock-in. Just add it and it works.

package/dist/client/components/index.d.cts

@@ -28,6 +28,19 @@ declare function RouteRenderer({ router, path, NotFoundComponent, onNotFound, on
     onError: (error: Error, info: ErrorInfo) => void;
     props?: any;
 }): react_jsx_runtime.JSX.Element;
+/**
+ * Renders a route with Suspense and ErrorBoundary wrappers.
+ * Handles loading states, error boundaries, and not-found scenarios for a single route.
+ *
+ * @param path - The current route path
+ * @param PageComponent - The page component to render
+ * @param ErrorComponent - Optional error fallback component
+ * @param LoadingComponent - Component to show during suspense
+ * @param onNotFound - Optional callback when route is not found
+ * @param NotFoundComponent - Optional component to show for 404s
+ * @param props - Additional props to pass to the page component
+ * @param onError - Error handler callback for the error boundary
+ */
 declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingComponent, onNotFound, NotFoundComponent, props, onError, }: {
     path: string;
     PageComponent: react__default.ComponentType<any>;
@@ -41,6 +54,15 @@ declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingCom
     onError: (error: Error, info: ErrorInfo) => void;
 }): react_jsx_runtime.JSX.Element | undefined;
 
+/**
+ * Error boundary wrapper component for catching and handling React errors.
+ * Wraps react-error-boundary with a simplified API.
+ *
+ * @param children - Child components to wrap with error boundary
+ * @param FallbackComponent - Component to render when an error occurs
+ * @param resetKeys - Array of values that will reset the error boundary when changed
+ * @param onError - Callback invoked when an error is caught
+ */
 declare function ErrorBoundary({ children, FallbackComponent, resetKeys, onError, }: {
     children: React.ReactNode;
     FallbackComponent: React.ComponentType<FallbackProps>;

package/dist/client/components/index.d.mts

@@ -28,6 +28,19 @@ declare function RouteRenderer({ router, path, NotFoundComponent, onNotFound, on
     onError: (error: Error, info: ErrorInfo) => void;
     props?: any;
 }): react_jsx_runtime.JSX.Element;
+/**
+ * Renders a route with Suspense and ErrorBoundary wrappers.
+ * Handles loading states, error boundaries, and not-found scenarios for a single route.
+ *
+ * @param path - The current route path
+ * @param PageComponent - The page component to render
+ * @param ErrorComponent - Optional error fallback component
+ * @param LoadingComponent - Component to show during suspense
+ * @param onNotFound - Optional callback when route is not found
+ * @param NotFoundComponent - Optional component to show for 404s
+ * @param props - Additional props to pass to the page component
+ * @param onError - Error handler callback for the error boundary
+ */
 declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingComponent, onNotFound, NotFoundComponent, props, onError, }: {
     path: string;
     PageComponent: react__default.ComponentType<any>;
@@ -41,6 +54,15 @@ declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingCom
     onError: (error: Error, info: ErrorInfo) => void;
 }): react_jsx_runtime.JSX.Element | undefined;
 
+/**
+ * Error boundary wrapper component for catching and handling React errors.
+ * Wraps react-error-boundary with a simplified API.
+ *
+ * @param children - Child components to wrap with error boundary
+ * @param FallbackComponent - Component to render when an error occurs
+ * @param resetKeys - Array of values that will reset the error boundary when changed
+ * @param onError - Callback invoked when an error is caught
+ */
 declare function ErrorBoundary({ children, FallbackComponent, resetKeys, onError, }: {
     children: React.ReactNode;
     FallbackComponent: React.ComponentType<FallbackProps>;

package/dist/client/components/index.d.ts

@@ -28,6 +28,19 @@ declare function RouteRenderer({ router, path, NotFoundComponent, onNotFound, on
     onError: (error: Error, info: ErrorInfo) => void;
     props?: any;
 }): react_jsx_runtime.JSX.Element;
+/**
+ * Renders a route with Suspense and ErrorBoundary wrappers.
+ * Handles loading states, error boundaries, and not-found scenarios for a single route.
+ *
+ * @param path - The current route path
+ * @param PageComponent - The page component to render
+ * @param ErrorComponent - Optional error fallback component
+ * @param LoadingComponent - Component to show during suspense
+ * @param onNotFound - Optional callback when route is not found
+ * @param NotFoundComponent - Optional component to show for 404s
+ * @param props - Additional props to pass to the page component
+ * @param onError - Error handler callback for the error boundary
+ */
 declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingComponent, onNotFound, NotFoundComponent, props, onError, }: {
     path: string;
     PageComponent: react__default.ComponentType<any>;
@@ -41,6 +54,15 @@ declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingCom
     onError: (error: Error, info: ErrorInfo) => void;
 }): react_jsx_runtime.JSX.Element | undefined;
 
+/**
+ * Error boundary wrapper component for catching and handling React errors.
+ * Wraps react-error-boundary with a simplified API.
+ *
+ * @param children - Child components to wrap with error boundary
+ * @param FallbackComponent - Component to render when an error occurs
+ * @param resetKeys - Array of values that will reset the error boundary when changed
+ * @param onError - Callback invoked when an error is caught
+ */
 declare function ErrorBoundary({ children, FallbackComponent, resetKeys, onError, }: {
     children: React.ReactNode;
     FallbackComponent: React.ComponentType<FallbackProps>;

package/dist/context/index.d.cts

@@ -50,8 +50,16 @@ declare function BetterStackProvider<TPluginOverrides extends Record<string, any
     basePath: string;
 }): react_jsx_runtime.JSX.Element;
 /**
- * Hook to access the entire context
+ * Hook to access the entire BetterStack context
  * Useful if you need access to multiple plugins or the full context
+ *
+ * @returns The full context value including overrides and basePath
+ * @throws Error if used outside of BetterStackProvider
+ *
+ * @example
+ * ```tsx
+ * const { overrides, basePath } = useBetterStack<MyPluginOverrides>();
+ * ```
  */
 declare function useBetterStack<TPluginOverrides extends Record<string, any> = Record<string, any>>(): BetterStackContextValue<TPluginOverrides>;
 type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults ? TOverrides : TOverrides & Required<Pick<TDefaults & {}, keyof TDefaults>>;
@@ -81,6 +89,18 @@ type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults ? TOve
  * ```
  */
 declare function usePluginOverrides<TOverrides = any, TDefaults extends Partial<TOverrides> | undefined = undefined>(pluginName: string, defaultValues?: TDefaults): OverridesResult<TOverrides, TDefaults>;
+/**
+ * Hook to access the base path where the client router is mounted
+ *
+ * @returns The base path string (e.g., "/pages")
+ * @throws Error if used outside of BetterStackProvider
+ *
+ * @example
+ * ```tsx
+ * const basePath = useBasePath();
+ * // basePath = "/pages"
+ * ```
+ */
 declare function useBasePath(): string;
 
 export { BetterStackProvider, useBasePath, useBetterStack, usePluginOverrides };

package/dist/context/index.d.mts

@@ -50,8 +50,16 @@ declare function BetterStackProvider<TPluginOverrides extends Record<string, any
     basePath: string;
 }): react_jsx_runtime.JSX.Element;
 /**
- * Hook to access the entire context
+ * Hook to access the entire BetterStack context
  * Useful if you need access to multiple plugins or the full context
+ *
+ * @returns The full context value including overrides and basePath
+ * @throws Error if used outside of BetterStackProvider
+ *
+ * @example
+ * ```tsx
+ * const { overrides, basePath } = useBetterStack<MyPluginOverrides>();
+ * ```
  */
 declare function useBetterStack<TPluginOverrides extends Record<string, any> = Record<string, any>>(): BetterStackContextValue<TPluginOverrides>;
 type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults ? TOverrides : TOverrides & Required<Pick<TDefaults & {}, keyof TDefaults>>;
@@ -81,6 +89,18 @@ type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults ? TOve
  * ```
  */
 declare function usePluginOverrides<TOverrides = any, TDefaults extends Partial<TOverrides> | undefined = undefined>(pluginName: string, defaultValues?: TDefaults): OverridesResult<TOverrides, TDefaults>;
+/**
+ * Hook to access the base path where the client router is mounted
+ *
+ * @returns The base path string (e.g., "/pages")
+ * @throws Error if used outside of BetterStackProvider
+ *
+ * @example
+ * ```tsx
+ * const basePath = useBasePath();
+ * // basePath = "/pages"
+ * ```
+ */
 declare function useBasePath(): string;
 
 export { BetterStackProvider, useBasePath, useBetterStack, usePluginOverrides };

package/dist/context/index.d.ts

@@ -50,8 +50,16 @@ declare function BetterStackProvider<TPluginOverrides extends Record<string, any
     basePath: string;
 }): react_jsx_runtime.JSX.Element;
 /**
- * Hook to access the entire context
+ * Hook to access the entire BetterStack context
  * Useful if you need access to multiple plugins or the full context
+ *
+ * @returns The full context value including overrides and basePath
+ * @throws Error if used outside of BetterStackProvider
+ *
+ * @example
+ * ```tsx
+ * const { overrides, basePath } = useBetterStack<MyPluginOverrides>();
+ * ```
  */
 declare function useBetterStack<TPluginOverrides extends Record<string, any> = Record<string, any>>(): BetterStackContextValue<TPluginOverrides>;
 type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults ? TOverrides : TOverrides & Required<Pick<TDefaults & {}, keyof TDefaults>>;
@@ -81,6 +89,18 @@ type OverridesResult<TOverrides, TDefaults> = undefined extends TDefaults ? TOve
  * ```
  */
 declare function usePluginOverrides<TOverrides = any, TDefaults extends Partial<TOverrides> | undefined = undefined>(pluginName: string, defaultValues?: TDefaults): OverridesResult<TOverrides, TDefaults>;
+/**
+ * Hook to access the base path where the client router is mounted
+ *
+ * @returns The base path string (e.g., "/pages")
+ * @throws Error if used outside of BetterStackProvider
+ *
+ * @example
+ * ```tsx
+ * const basePath = useBasePath();
+ * // basePath = "/pages"
+ * ```
+ */
 declare function useBasePath(): string;
 
 export { BetterStackProvider, useBasePath, useBetterStack, usePluginOverrides };

package/dist/packages/better-stack/src/plugins/blog/client/components/shared/on-this-page.cjs

@@ -7,6 +7,7 @@ const utils = require('../../../utils.cjs');
 const context = require('@btst/stack/context');
 const index = require('../../localization/index.cjs');
 const select = require('../../../../../../../ui/src/components/select.cjs');
+const lucideReact = require('lucide-react');
 
 function OnThisPage({ markdown, className }) {
   const { localization } = context.usePluginOverrides("blog", {
@@ -39,8 +40,12 @@ function OnThisPage({ markdown, className }) {
         className
       ),
       "aria-label": "Table of contents",
-      children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "overflow-y-auto px-2", children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-2 p-4 pt-0 text-sm", children: [
-        /* @__PURE__ */ jsxRuntime.jsx("p", { className: "font-semibold text-muted-foreground sticky top-0 h-6 text-xs", children: localization.BLOG_POST_ON_THIS_PAGE }),
+      children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "overflow-y-auto px-2", children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-1 p-4 pt-0 text-sm", children: [
+        /* @__PURE__ */ jsxRuntime.jsxs("p", { className: "flex items-center gap-2 font-semibold text-muted-foreground sticky top-0 h-6 text-xs", children: [
+          /* @__PURE__ */ jsxRuntime.jsx(lucideReact.TextAlignStart, { className: "w-3 h-3" }),
+          " ",
+          localization.BLOG_POST_ON_THIS_PAGE
+        ] }),
         headings.map(({ id, text, level }) => {
           const paddingLeft = level === 1 ? "0" : level === 2 ? "0.5rem" : level === 3 ? "1rem" : level === 4 ? "1.5rem" : level === 5 ? "2rem" : level === 6 ? "2.5rem" : "0";
           return /* @__PURE__ */ jsxRuntime.jsx(

package/dist/packages/better-stack/src/plugins/blog/client/components/shared/on-this-page.mjs

@@ -5,6 +5,7 @@ import { cn, slugify } from '../../../utils.mjs';
 import { usePluginOverrides } from '@btst/stack/context';
 import { BLOG_LOCALIZATION } from '../../localization/index.mjs';
 import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../../../../../../../ui/src/components/select.mjs';
+import { TextAlignStart } from 'lucide-react';
 
 function OnThisPage({ markdown, className }) {
   const { localization } = usePluginOverrides("blog", {
@@ -37,8 +38,12 @@ function OnThisPage({ markdown, className }) {
         className
       ),
       "aria-label": "Table of contents",
-      children: /* @__PURE__ */ jsx("div", { className: "overflow-y-auto px-2", children: /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-2 p-4 pt-0 text-sm", children: [
-        /* @__PURE__ */ jsx("p", { className: "font-semibold text-muted-foreground sticky top-0 h-6 text-xs", children: localization.BLOG_POST_ON_THIS_PAGE }),
+      children: /* @__PURE__ */ jsx("div", { className: "overflow-y-auto px-2", children: /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1 p-4 pt-0 text-sm", children: [
+        /* @__PURE__ */ jsxs("p", { className: "flex items-center gap-2 font-semibold text-muted-foreground sticky top-0 h-6 text-xs", children: [
+          /* @__PURE__ */ jsx(TextAlignStart, { className: "w-3 h-3" }),
+          " ",
+          localization.BLOG_POST_ON_THIS_PAGE
+        ] }),
         headings.map(({ id, text, level }) => {
           const paddingLeft = level === 1 ? "0" : level === 2 ? "0.5rem" : level === 3 ? "1rem" : level === 4 ? "1.5rem" : level === 5 ? "2rem" : level === 6 ? "2.5rem" : "0";
           return /* @__PURE__ */ jsx(

package/dist/plugins/blog/client/hooks/index.d.cts

@@ -2,47 +2,94 @@ import * as _tanstack_react_query from '@tanstack/react-query';
 import { S as SerializedPost, c as createPostSchema, u as updatePostSchema, a as SerializedTag } from '../../../../shared/stack.Cr2JoQdo.cjs';
 import { z } from 'zod';
 
+/**
+ * Options for the usePosts hook
+ */
 interface UsePostsOptions {
+    /** Filter posts by tag name */
     tag?: string;
+    /** Filter posts by tag slug */
     tagSlug?: string;
+    /** Number of posts to fetch per page (default: 10) */
     limit?: number;
+    /** Whether to enable the query (default: true) */
     enabled?: boolean;
+    /** Search query to filter posts by title, content, or excerpt */
     query?: string;
+    /** Filter by published status */
     published?: boolean;
+    /** Filter by specific post slug */
     slug?: string;
 }
+/**
+ * Result from the usePosts hook
+ */
 interface UsePostsResult {
+    /** Array of fetched posts */
     posts: SerializedPost[];
+    /** Whether the initial load is in progress */
     isLoading: boolean;
+    /** Error if the query failed */
     error: Error | null;
+    /** Function to load the next page of posts */
     loadMore: () => void;
+    /** Whether there are more posts to load */
     hasMore: boolean;
+    /** Whether the next page is being loaded */
     isLoadingMore: boolean;
+    /** Function to refetch the posts */
     refetch: () => void;
 }
+/**
+ * Options for the usePostSearch hook
+ */
 interface UsePostSearchOptions {
+    /** Search query string to filter posts */
     query: string;
+    /** Whether to enable the search query (default: true) */
     enabled?: boolean;
+    /** Debounce delay in milliseconds (default: 300) */
     debounceMs?: number;
+    /** Number of results to return (default: 10) */
     limit?: number;
+    /** Filter by published status (default: true) */
     published?: boolean;
 }
+/**
+ * Result from the usePostSearch hook
+ */
 interface UsePostSearchResult {
+    /** Array of posts matching the search query */
     posts: SerializedPost[];
+    /** Alias for posts (React Query compatibility) */
     data: SerializedPost[];
+    /** Whether the search is in progress */
     isLoading: boolean;
+    /** Error if the search failed */
     error: Error | null;
+    /** Function to refetch the search results */
     refetch: () => void;
+    /** Whether a search is currently in progress (includes debounce time) */
     isSearching: boolean;
+    /** The debounced search query being used */
     searchQuery: string;
 }
+/**
+ * Result from the usePost hook
+ */
 interface UsePostResult {
+    /** The fetched post, or null if not found */
     post: SerializedPost | null;
+    /** Whether the post is being loaded */
     isLoading: boolean;
+    /** Error if the query failed */
     error: Error | null;
+    /** Function to refetch the post */
     refetch: () => void;
 }
+/** Input type for creating a new post */
 type PostCreateInput = z.infer<typeof createPostSchema>;
+/** Input type for updating an existing post */
 type PostUpdateInput = z.infer<typeof updatePostSchema>;
 /**
  * Hook for fetching paginated posts with load more functionality
@@ -114,14 +161,26 @@ declare function useDeletePost(): _tanstack_react_query.UseMutationResult<{
  * Debounces the query and preserves last successful results to avoid flicker.
  */
 declare function usePostSearch({ query, enabled, debounceMs, limit, published, }: UsePostSearchOptions): UsePostSearchResult;
+/**
+ * Options for the useNextPreviousPosts hook
+ */
 interface UseNextPreviousPostsOptions {
+    /** Whether to enable the query (default: true) */
     enabled?: boolean;
 }
+/**
+ * Result from the useNextPreviousPosts hook
+ */
 interface UseNextPreviousPostsResult {
+    /** The previous post (older), or null if none exists */
     previousPost: SerializedPost | null;
+    /** The next post (newer), or null if none exists */
     nextPost: SerializedPost | null;
+    /** Whether the query is loading */
     isLoading: boolean;
+    /** Error if the query failed */
     error: Error | null;
+    /** Function to refetch the posts */
     refetch: () => void;
 }
 /**
@@ -132,15 +191,28 @@ declare function useNextPreviousPosts(createdAt: string | Date, options?: UseNex
     ref: (node: Element | null) => void;
     inView: boolean;
 };
+/**
+ * Options for the useRecentPosts hook
+ */
 interface UseRecentPostsOptions {
+    /** Maximum number of recent posts to fetch (default: 5) */
     limit?: number;
+    /** Slug of a post to exclude from results */
     excludeSlug?: string;
+    /** Whether to enable the query (default: true) */
     enabled?: boolean;
 }
+/**
+ * Result from the useRecentPosts hook
+ */
 interface UseRecentPostsResult {
+    /** Array of recent posts */
     recentPosts: SerializedPost[];
+    /** Whether the query is loading */
     isLoading: boolean;
+    /** Error if the query failed */
     error: Error | null;
+    /** Function to refetch the posts */
     refetch: () => void;
 }
 /**