@cstar.help/react 0.2.0 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 React hooks for the [cStar](https://cstar.help) customer support platform. Build custom chat widgets and knowledge base UIs with type-safe, SSR-compatible hooks.
 
 - **React 18+** — hooks with automatic loading states and error handling
-- **Two modules** — Chat (real-time messaging) and Library (knowledge base)
+- **Three modules** — Chat (real-time messaging), Library (knowledge base), and Community (forum)
 - **TypeScript-first** — full type definitions included
 - **Tiny** — ~18 KB, tree-shakeable, only peer deps
 
@@ -182,6 +182,87 @@ function SearchBar() {
 }
 ```
 
+## Community
+
+Wrap in `<CStarCommunityProvider>` for public community forum access — no auth required.
+
+### Setup
+
+```tsx
+import { CStarCommunityProvider } from '@cstar.help/react';
+
+function App() {
+	return (
+		<CStarCommunityProvider teamSlug="acme">
+			<CommunityForum />
+		</CStarCommunityProvider>
+	);
+}
+```
+
+### Topics + Posts
+
+```tsx
+import { useTopics, usePosts, usePost } from '@cstar.help/react';
+
+function CommunityForum() {
+	const { topics, isLoading: topicsLoading } = useTopics();
+	const { posts, count, isLoading: postsLoading } = usePosts({ sort: 'votes' });
+
+	return (
+		<>
+			<nav>
+				{topics.map((topic) => (
+					<a key={topic.id}>{topic.name}</a>
+				))}
+			</nav>
+			<p>{count} posts</p>
+			<ul>
+				{posts.map((post) => (
+					<li key={post.id}>
+						{post.title} — {post.voteCount} votes
+					</li>
+				))}
+			</ul>
+		</>
+	);
+}
+
+// Single post with comments
+function PostPage({ slug }) {
+	const { data, isLoading, error } = usePost(slug);
+	if (isLoading) return <Spinner />;
+	if (!data) return <NotFound />;
+	return (
+		<>
+			<h1>{data.post.title}</h1>
+			{data.comments.map((c) => (
+				<p key={c.id}>{c.body}</p>
+			))}
+		</>
+	);
+}
+```
+
+### Search
+
+```tsx
+import { useCommunitySearch } from '@cstar.help/react';
+
+function CommunitySearch() {
+	const { results, isLoading, search } = useCommunitySearch();
+
+	return (
+		<>
+			<input onChange={(e) => search(e.target.value)} placeholder="Search posts..." />
+			{results?.data.map((post) => (
+				<a key={post.id}>{post.title}</a>
+			))}
+		</>
+	);
+}
+```
+
 ## API Reference
 
 ### Chat Hooks
@@ -202,12 +283,22 @@ function SearchBar() {
 | `useArticle(slug)`        | `{ article, isLoading, error, refresh }`    | Single article by slug                    |
 | `useArticleSearch(query)` | `{ results, totalCount, isLoading, error }` | Search with 300ms debounce                |
 
+### Community Hooks
+
+| Hook                   | Returns                                       | Description                                           |
+| ---------------------- | --------------------------------------------- | ----------------------------------------------------- |
+| `useTopics()`          | `{ topics, isLoading, error, refresh }`       | Community discussion topics                           |
+| `usePosts(params?)`    | `{ posts, count, isLoading, error, refresh }` | Posts with optional filters (topicSlug, status, sort) |
+| `usePost(slug)`        | `{ data, isLoading, error, refresh }`         | Single post with comments                             |
+| `useCommunitySearch()` | `{ results, isLoading, error, search }`       | On-demand search across posts                         |
+
 ### Context Accessors
 
-| Function             | Returns         | Description                                    |
-| -------------------- | --------------- | ---------------------------------------------- |
-| `useChatClient()`    | `ChatClient`    | Raw client from nearest `CStarChatProvider`    |
-| `useLibraryClient()` | `LibraryClient` | Raw client from nearest `CStarLibraryProvider` |
+| Function               | Returns           | Description                                      |
+| ---------------------- | ----------------- | ------------------------------------------------ |
+| `useChatClient()`      | `ChatClient`      | Raw client from nearest `CStarChatProvider`      |
+| `useLibraryClient()`   | `LibraryClient`   | Raw client from nearest `CStarLibraryProvider`   |
+| `useCommunityClient()` | `CommunityClient` | Raw client from nearest `CStarCommunityProvider` |
 
 ## Requirements
 

package/dist/index.cjs

@@ -22,6 +22,8 @@ var src_exports = {};
 __export(src_exports, {
   CStarChatContext: () => CStarChatContext,
   CStarChatProvider: () => CStarChatProvider,
+  CStarCommunityContext: () => CStarCommunityContext,
+  CStarCommunityProvider: () => CStarCommunityProvider,
   CStarLibraryContext: () => CStarLibraryContext,
   CStarLibraryProvider: () => CStarLibraryProvider,
   useArticle: () => useArticle,
@@ -30,9 +32,14 @@ __export(src_exports, {
   useCategories: () => useCategories,
   useChat: () => useChat,
   useChatClient: () => useChatClient,
+  useCommunityClient: () => useCommunityClient,
+  useCommunitySearch: () => useCommunitySearch,
   useConversations: () => useConversations,
   useLibraryClient: () => useLibraryClient,
   useMessages: () => useMessages,
+  usePost: () => usePost,
+  usePosts: () => usePosts,
+  useTopics: () => useTopics,
   useTyping: () => useTyping
 });
 module.exports = __toCommonJS(src_exports);
@@ -41,6 +48,7 @@ module.exports = __toCommonJS(src_exports);
 var import_react = require("react");
 var CStarChatContext = (0, import_react.createContext)(null);
 var CStarLibraryContext = (0, import_react.createContext)(null);
+var CStarCommunityContext = (0, import_react.createContext)(null);
 function useChatClient() {
   const client = (0, import_react.useContext)(CStarChatContext);
   if (!client) {
@@ -55,6 +63,13 @@ function useLibraryClient() {
   }
   return client;
 }
+function useCommunityClient() {
+  const client = (0, import_react.useContext)(CStarCommunityContext);
+  if (!client) {
+    throw new Error("useCommunityClient must be used within a <CStarCommunityProvider>");
+  }
+  return client;
+}
 
 // src/chat/CStarChatProvider.tsx
 var import_react2 = require("react");
@@ -412,6 +427,13 @@ function useArticle(slug) {
       }
     }
   }, [client, slug]);
+  const recordView = (0, import_react10.useCallback)(async () => {
+    if (!slug) return;
+    try {
+      await client.recordView(slug);
+    } catch {
+    }
+  }, [client, slug]);
   (0, import_react10.useEffect)(() => {
     mountedRef.current = true;
     if (!slug) {
@@ -424,7 +446,7 @@ function useArticle(slug) {
       mountedRef.current = false;
     };
   }, [slug, refresh]);
-  return { article, isLoading, error, refresh };
+  return { article, isLoading, error, refresh, recordView };
 }
 
 // src/library/useArticleSearch.ts
@@ -473,10 +495,181 @@ function useArticleSearch(query) {
   }, [client, query]);
   return { results, totalCount, isLoading, error };
 }
+
+// src/community/CStarCommunityProvider.tsx
+var import_react12 = require("react");
+var import_community = require("@cstar.help/js/community");
+var import_jsx_runtime3 = require("react/jsx-runtime");
+function CStarCommunityProvider({ children, ...config }) {
+  const clientRef = (0, import_react12.useRef)(null);
+  if (!clientRef.current) {
+    clientRef.current = new import_community.CommunityClient(config);
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(CStarCommunityContext.Provider, { value: clientRef.current, children });
+}
+
+// src/community/useTopics.ts
+var import_react13 = require("react");
+function useTopics() {
+  const client = useCommunityClient();
+  const [topics, setTopics] = (0, import_react13.useState)([]);
+  const [isLoading, setIsLoading] = (0, import_react13.useState)(true);
+  const [error, setError] = (0, import_react13.useState)(null);
+  const mountedRef = (0, import_react13.useRef)(true);
+  const refresh = (0, import_react13.useCallback)(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await client.topics();
+      if (mountedRef.current) {
+        setTopics(data);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client]);
+  (0, import_react13.useEffect)(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+  return { topics, isLoading, error, refresh };
+}
+
+// src/community/usePosts.ts
+var import_react14 = require("react");
+function usePosts(params) {
+  const client = useCommunityClient();
+  const [posts, setPosts] = (0, import_react14.useState)([]);
+  const [count, setCount] = (0, import_react14.useState)(0);
+  const [isLoading, setIsLoading] = (0, import_react14.useState)(true);
+  const [error, setError] = (0, import_react14.useState)(null);
+  const mountedRef = (0, import_react14.useRef)(true);
+  const topicSlug = params?.topicSlug;
+  const status = params?.status;
+  const sort = params?.sort;
+  const limit = params?.limit;
+  const offset = params?.offset;
+  const refresh = (0, import_react14.useCallback)(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await client.posts({ topicSlug, status, sort, limit, offset });
+      if (mountedRef.current) {
+        setPosts(result.posts);
+        setCount(result.count);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client, topicSlug, status, sort, limit, offset]);
+  (0, import_react14.useEffect)(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+  return { posts, count, isLoading, error, refresh };
+}
+
+// src/community/usePost.ts
+var import_react15 = require("react");
+function usePost(slug) {
+  const client = useCommunityClient();
+  const [data, setData] = (0, import_react15.useState)(null);
+  const [isLoading, setIsLoading] = (0, import_react15.useState)(true);
+  const [error, setError] = (0, import_react15.useState)(null);
+  const mountedRef = (0, import_react15.useRef)(true);
+  const refresh = (0, import_react15.useCallback)(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await client.post(slug);
+      if (mountedRef.current) {
+        setData(result);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client, slug]);
+  (0, import_react15.useEffect)(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+  return { data, isLoading, error, refresh };
+}
+
+// src/community/useCommunitySearch.ts
+var import_react16 = require("react");
+function useCommunitySearch() {
+  const client = useCommunityClient();
+  const [results, setResults] = (0, import_react16.useState)(null);
+  const [isLoading, setIsLoading] = (0, import_react16.useState)(false);
+  const [error, setError] = (0, import_react16.useState)(null);
+  const mountedRef = (0, import_react16.useRef)(true);
+  (0, import_react16.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  const search = (0, import_react16.useCallback)(
+    async (query) => {
+      if (!query.trim()) {
+        setResults(null);
+        return;
+      }
+      setIsLoading(true);
+      setError(null);
+      try {
+        const data = await client.search(query);
+        if (mountedRef.current) {
+          setResults(data);
+        }
+      } catch (err) {
+        if (mountedRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
+      } finally {
+        if (mountedRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [client]
+  );
+  return { results, isLoading, error, search };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CStarChatContext,
   CStarChatProvider,
+  CStarCommunityContext,
+  CStarCommunityProvider,
   CStarLibraryContext,
   CStarLibraryProvider,
   useArticle,
@@ -485,8 +678,13 @@ function useArticleSearch(query) {
   useCategories,
   useChat,
   useChatClient,
+  useCommunityClient,
+  useCommunitySearch,
   useConversations,
   useLibraryClient,
   useMessages,
+  usePost,
+  usePosts,
+  useTopics,
   useTyping
 });

package/dist/index.d.cts

@@ -4,10 +4,13 @@ import { ChatClient, ChatConfig, IdentifyParams, IdentifyResult, Conversation, C
 export { ChatConfig, Conversation, ConversationCreateParams, ConversationListResponse, IdentifyParams, IdentifyResult, TypingPayload, WidgetMessage } from '@cstar.help/js/chat';
 import { LibraryClient, LibraryConfig, Category, LibraryArticle, LibraryArticleListParams } from '@cstar.help/js/library';
 export { Category, LibraryArticle, LibraryArticleListParams, LibraryConfig, LibrarySearchParams, LibrarySearchResult } from '@cstar.help/js/library';
+import { CommunityClient, CommunityConfig, CommunityTopic, CommunityPost, CommunityPostListParams, CommunityPostDetail, CommunitySearchResult } from '@cstar.help/js/community';
+export { CommunityComment, CommunityConfig, CommunityPost, CommunityPostDetail, CommunityPostListParams, CommunitySearchResult, CommunityTopic } from '@cstar.help/js/community';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 declare const CStarChatContext: react.Context<ChatClient | null>;
 declare const CStarLibraryContext: react.Context<LibraryClient | null>;
+declare const CStarCommunityContext: react.Context<CommunityClient | null>;
 /**
  * Access the ChatClient from the nearest CStarChatProvider.
  * Throws if used outside a provider.
@@ -18,6 +21,11 @@ declare function useChatClient(): ChatClient;
  * Throws if used outside a provider.
  */
 declare function useLibraryClient(): LibraryClient;
+/**
+ * Access the CommunityClient from the nearest CStarCommunityProvider.
+ * Throws if used outside a provider.
+ */
+declare function useCommunityClient(): CommunityClient;
 
 interface CStarChatProviderProps extends ChatConfig {
     children: ReactNode;
@@ -185,6 +193,8 @@ interface UseArticleReturn {
     error: Error | null;
     /** Re-fetch the article. */
     refresh: () => Promise<void>;
+    /** Record a view for this article. Call once when the article page mounts. */
+    recordView: () => Promise<void>;
 }
 /**
  * Fetch a single article by slug.
@@ -215,4 +225,99 @@ interface UseArticleSearchReturn {
  */
 declare function useArticleSearch(query: string): UseArticleSearchReturn;
 
-export { CStarChatContext, CStarChatProvider, type CStarChatProviderProps, CStarLibraryContext, CStarLibraryProvider, type CStarLibraryProviderProps, type TypingAgent, type UseArticleReturn, type UseArticleSearchReturn, type UseArticlesReturn, type UseCategoriesReturn, type UseChatReturn, type UseConversationsReturn, type UseMessagesReturn, type UseTypingReturn, useArticle, useArticleSearch, useArticles, useCategories, useChat, useChatClient, useConversations, useLibraryClient, useMessages, useTyping };
+interface CStarCommunityProviderProps extends CommunityConfig {
+    children: ReactNode;
+}
+/**
+ * Provides a CommunityClient instance to all child components.
+ *
+ * ```tsx
+ * <CStarCommunityProvider teamSlug="acme">
+ *   <CommunityForum />
+ * </CStarCommunityProvider>
+ * ```
+ */
+declare function CStarCommunityProvider({ children, ...config }: CStarCommunityProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseTopicsReturn {
+    /** Community discussion topics. */
+    topics: CommunityTopic[];
+    /** Whether the fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Re-fetch topics. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch community discussion topics.
+ *
+ * ```tsx
+ * const { topics, isLoading } = useTopics();
+ * ```
+ */
+declare function useTopics(): UseTopicsReturn;
+
+interface UsePostsReturn {
+    /** Community posts. */
+    posts: CommunityPost[];
+    /** Total count of matching posts (for pagination). */
+    count: number;
+    /** Whether the fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Re-fetch posts with the current params. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch community posts with optional filters.
+ *
+ * ```tsx
+ * const { posts, isLoading } = usePosts({ topicSlug: 'feedback', sort: 'votes' });
+ * ```
+ */
+declare function usePosts(params?: CommunityPostListParams): UsePostsReturn;
+
+interface UsePostReturn {
+    /** The post with comments, or null if not loaded. */
+    data: CommunityPostDetail | null;
+    /** Whether the fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Re-fetch the post. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch a single community post by slug, including all comments.
+ *
+ * ```tsx
+ * const { data, isLoading } = usePost('dark-mode-support');
+ * ```
+ */
+declare function usePost(slug: string): UsePostReturn;
+
+interface UseCommunitySearchReturn {
+    /** Search results (null until first search). */
+    results: CommunitySearchResult | null;
+    /** Whether a search is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Execute a search query. */
+    search: (query: string) => Promise<void>;
+}
+/**
+ * Search community posts by title and body content.
+ *
+ * ```tsx
+ * const { results, isLoading, search } = useCommunitySearch();
+ *
+ * <input onChange={(e) => search(e.target.value)} />
+ * {results?.data.map(post => <PostCard key={post.id} post={post} />)}
+ * ```
+ */
+declare function useCommunitySearch(): UseCommunitySearchReturn;
+
+export { CStarChatContext, CStarChatProvider, type CStarChatProviderProps, CStarCommunityContext, CStarCommunityProvider, type CStarCommunityProviderProps, CStarLibraryContext, CStarLibraryProvider, type CStarLibraryProviderProps, type TypingAgent, type UseArticleReturn, type UseArticleSearchReturn, type UseArticlesReturn, type UseCategoriesReturn, type UseChatReturn, type UseCommunitySearchReturn, type UseConversationsReturn, type UseMessagesReturn, type UsePostReturn, type UsePostsReturn, type UseTopicsReturn, type UseTypingReturn, useArticle, useArticleSearch, useArticles, useCategories, useChat, useChatClient, useCommunityClient, useCommunitySearch, useConversations, useLibraryClient, useMessages, usePost, usePosts, useTopics, useTyping };

package/dist/index.d.ts

@@ -4,10 +4,13 @@ import { ChatClient, ChatConfig, IdentifyParams, IdentifyResult, Conversation, C
 export { ChatConfig, Conversation, ConversationCreateParams, ConversationListResponse, IdentifyParams, IdentifyResult, TypingPayload, WidgetMessage } from '@cstar.help/js/chat';
 import { LibraryClient, LibraryConfig, Category, LibraryArticle, LibraryArticleListParams } from '@cstar.help/js/library';
 export { Category, LibraryArticle, LibraryArticleListParams, LibraryConfig, LibrarySearchParams, LibrarySearchResult } from '@cstar.help/js/library';
+import { CommunityClient, CommunityConfig, CommunityTopic, CommunityPost, CommunityPostListParams, CommunityPostDetail, CommunitySearchResult } from '@cstar.help/js/community';
+export { CommunityComment, CommunityConfig, CommunityPost, CommunityPostDetail, CommunityPostListParams, CommunitySearchResult, CommunityTopic } from '@cstar.help/js/community';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 declare const CStarChatContext: react.Context<ChatClient | null>;
 declare const CStarLibraryContext: react.Context<LibraryClient | null>;
+declare const CStarCommunityContext: react.Context<CommunityClient | null>;
 /**
  * Access the ChatClient from the nearest CStarChatProvider.
  * Throws if used outside a provider.
@@ -18,6 +21,11 @@ declare function useChatClient(): ChatClient;
  * Throws if used outside a provider.
  */
 declare function useLibraryClient(): LibraryClient;
+/**
+ * Access the CommunityClient from the nearest CStarCommunityProvider.
+ * Throws if used outside a provider.
+ */
+declare function useCommunityClient(): CommunityClient;
 
 interface CStarChatProviderProps extends ChatConfig {
     children: ReactNode;
@@ -185,6 +193,8 @@ interface UseArticleReturn {
     error: Error | null;
     /** Re-fetch the article. */
     refresh: () => Promise<void>;
+    /** Record a view for this article. Call once when the article page mounts. */
+    recordView: () => Promise<void>;
 }
 /**
  * Fetch a single article by slug.
@@ -215,4 +225,99 @@ interface UseArticleSearchReturn {
  */
 declare function useArticleSearch(query: string): UseArticleSearchReturn;
 
-export { CStarChatContext, CStarChatProvider, type CStarChatProviderProps, CStarLibraryContext, CStarLibraryProvider, type CStarLibraryProviderProps, type TypingAgent, type UseArticleReturn, type UseArticleSearchReturn, type UseArticlesReturn, type UseCategoriesReturn, type UseChatReturn, type UseConversationsReturn, type UseMessagesReturn, type UseTypingReturn, useArticle, useArticleSearch, useArticles, useCategories, useChat, useChatClient, useConversations, useLibraryClient, useMessages, useTyping };
+interface CStarCommunityProviderProps extends CommunityConfig {
+    children: ReactNode;
+}
+/**
+ * Provides a CommunityClient instance to all child components.
+ *
+ * ```tsx
+ * <CStarCommunityProvider teamSlug="acme">
+ *   <CommunityForum />
+ * </CStarCommunityProvider>
+ * ```
+ */
+declare function CStarCommunityProvider({ children, ...config }: CStarCommunityProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseTopicsReturn {
+    /** Community discussion topics. */
+    topics: CommunityTopic[];
+    /** Whether the fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Re-fetch topics. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch community discussion topics.
+ *
+ * ```tsx
+ * const { topics, isLoading } = useTopics();
+ * ```
+ */
+declare function useTopics(): UseTopicsReturn;
+
+interface UsePostsReturn {
+    /** Community posts. */
+    posts: CommunityPost[];
+    /** Total count of matching posts (for pagination). */
+    count: number;
+    /** Whether the fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Re-fetch posts with the current params. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch community posts with optional filters.
+ *
+ * ```tsx
+ * const { posts, isLoading } = usePosts({ topicSlug: 'feedback', sort: 'votes' });
+ * ```
+ */
+declare function usePosts(params?: CommunityPostListParams): UsePostsReturn;
+
+interface UsePostReturn {
+    /** The post with comments, or null if not loaded. */
+    data: CommunityPostDetail | null;
+    /** Whether the fetch is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Re-fetch the post. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Fetch a single community post by slug, including all comments.
+ *
+ * ```tsx
+ * const { data, isLoading } = usePost('dark-mode-support');
+ * ```
+ */
+declare function usePost(slug: string): UsePostReturn;
+
+interface UseCommunitySearchReturn {
+    /** Search results (null until first search). */
+    results: CommunitySearchResult | null;
+    /** Whether a search is in progress. */
+    isLoading: boolean;
+    /** The last error, or null. */
+    error: Error | null;
+    /** Execute a search query. */
+    search: (query: string) => Promise<void>;
+}
+/**
+ * Search community posts by title and body content.
+ *
+ * ```tsx
+ * const { results, isLoading, search } = useCommunitySearch();
+ *
+ * <input onChange={(e) => search(e.target.value)} />
+ * {results?.data.map(post => <PostCard key={post.id} post={post} />)}
+ * ```
+ */
+declare function useCommunitySearch(): UseCommunitySearchReturn;
+
+export { CStarChatContext, CStarChatProvider, type CStarChatProviderProps, CStarCommunityContext, CStarCommunityProvider, type CStarCommunityProviderProps, CStarLibraryContext, CStarLibraryProvider, type CStarLibraryProviderProps, type TypingAgent, type UseArticleReturn, type UseArticleSearchReturn, type UseArticlesReturn, type UseCategoriesReturn, type UseChatReturn, type UseCommunitySearchReturn, type UseConversationsReturn, type UseMessagesReturn, type UsePostReturn, type UsePostsReturn, type UseTopicsReturn, type UseTypingReturn, useArticle, useArticleSearch, useArticles, useCategories, useChat, useChatClient, useCommunityClient, useCommunitySearch, useConversations, useLibraryClient, useMessages, usePost, usePosts, useTopics, useTyping };

package/dist/index.js

@@ -2,6 +2,7 @@
 import { createContext, useContext } from "react";
 var CStarChatContext = createContext(null);
 var CStarLibraryContext = createContext(null);
+var CStarCommunityContext = createContext(null);
 function useChatClient() {
   const client = useContext(CStarChatContext);
   if (!client) {
@@ -16,6 +17,13 @@ function useLibraryClient() {
   }
   return client;
 }
+function useCommunityClient() {
+  const client = useContext(CStarCommunityContext);
+  if (!client) {
+    throw new Error("useCommunityClient must be used within a <CStarCommunityProvider>");
+  }
+  return client;
+}
 
 // src/chat/CStarChatProvider.tsx
 import { useEffect, useRef } from "react";
@@ -373,6 +381,13 @@ function useArticle(slug) {
       }
     }
   }, [client, slug]);
+  const recordView = useCallback7(async () => {
+    if (!slug) return;
+    try {
+      await client.recordView(slug);
+    } catch {
+    }
+  }, [client, slug]);
   useEffect7(() => {
     mountedRef.current = true;
     if (!slug) {
@@ -385,7 +400,7 @@ function useArticle(slug) {
       mountedRef.current = false;
     };
   }, [slug, refresh]);
-  return { article, isLoading, error, refresh };
+  return { article, isLoading, error, refresh, recordView };
 }
 
 // src/library/useArticleSearch.ts
@@ -434,9 +449,180 @@ function useArticleSearch(query) {
   }, [client, query]);
   return { results, totalCount, isLoading, error };
 }
+
+// src/community/CStarCommunityProvider.tsx
+import { useRef as useRef10 } from "react";
+import { CommunityClient } from "@cstar.help/js/community";
+import { jsx as jsx3 } from "react/jsx-runtime";
+function CStarCommunityProvider({ children, ...config }) {
+  const clientRef = useRef10(null);
+  if (!clientRef.current) {
+    clientRef.current = new CommunityClient(config);
+  }
+  return /* @__PURE__ */ jsx3(CStarCommunityContext.Provider, { value: clientRef.current, children });
+}
+
+// src/community/useTopics.ts
+import { useState as useState9, useEffect as useEffect9, useCallback as useCallback8, useRef as useRef11 } from "react";
+function useTopics() {
+  const client = useCommunityClient();
+  const [topics, setTopics] = useState9([]);
+  const [isLoading, setIsLoading] = useState9(true);
+  const [error, setError] = useState9(null);
+  const mountedRef = useRef11(true);
+  const refresh = useCallback8(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await client.topics();
+      if (mountedRef.current) {
+        setTopics(data);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client]);
+  useEffect9(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+  return { topics, isLoading, error, refresh };
+}
+
+// src/community/usePosts.ts
+import { useState as useState10, useEffect as useEffect10, useCallback as useCallback9, useRef as useRef12 } from "react";
+function usePosts(params) {
+  const client = useCommunityClient();
+  const [posts, setPosts] = useState10([]);
+  const [count, setCount] = useState10(0);
+  const [isLoading, setIsLoading] = useState10(true);
+  const [error, setError] = useState10(null);
+  const mountedRef = useRef12(true);
+  const topicSlug = params?.topicSlug;
+  const status = params?.status;
+  const sort = params?.sort;
+  const limit = params?.limit;
+  const offset = params?.offset;
+  const refresh = useCallback9(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await client.posts({ topicSlug, status, sort, limit, offset });
+      if (mountedRef.current) {
+        setPosts(result.posts);
+        setCount(result.count);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client, topicSlug, status, sort, limit, offset]);
+  useEffect10(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+  return { posts, count, isLoading, error, refresh };
+}
+
+// src/community/usePost.ts
+import { useState as useState11, useEffect as useEffect11, useCallback as useCallback10, useRef as useRef13 } from "react";
+function usePost(slug) {
+  const client = useCommunityClient();
+  const [data, setData] = useState11(null);
+  const [isLoading, setIsLoading] = useState11(true);
+  const [error, setError] = useState11(null);
+  const mountedRef = useRef13(true);
+  const refresh = useCallback10(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await client.post(slug);
+      if (mountedRef.current) {
+        setData(result);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [client, slug]);
+  useEffect11(() => {
+    mountedRef.current = true;
+    refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+  return { data, isLoading, error, refresh };
+}
+
+// src/community/useCommunitySearch.ts
+import { useState as useState12, useEffect as useEffect12, useCallback as useCallback11, useRef as useRef14 } from "react";
+function useCommunitySearch() {
+  const client = useCommunityClient();
+  const [results, setResults] = useState12(null);
+  const [isLoading, setIsLoading] = useState12(false);
+  const [error, setError] = useState12(null);
+  const mountedRef = useRef14(true);
+  useEffect12(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  const search = useCallback11(
+    async (query) => {
+      if (!query.trim()) {
+        setResults(null);
+        return;
+      }
+      setIsLoading(true);
+      setError(null);
+      try {
+        const data = await client.search(query);
+        if (mountedRef.current) {
+          setResults(data);
+        }
+      } catch (err) {
+        if (mountedRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
+      } finally {
+        if (mountedRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [client]
+  );
+  return { results, isLoading, error, search };
+}
 export {
   CStarChatContext,
   CStarChatProvider,
+  CStarCommunityContext,
+  CStarCommunityProvider,
   CStarLibraryContext,
   CStarLibraryProvider,
   useArticle,
@@ -445,8 +631,13 @@ export {
   useCategories,
   useChat,
   useChatClient,
+  useCommunityClient,
+  useCommunitySearch,
   useConversations,
   useLibraryClient,
   useMessages,
+  usePost,
+  usePosts,
+  useTopics,
   useTyping
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cstar.help/react",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "React hooks for the cStar customer support platform",
 	"type": "module",
 	"main": "./dist/index.cjs",