@cstar.help/react 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -24,19 +24,28 @@ __export(src_exports, {
   CStarChatProvider: () => CStarChatProvider,
   CStarCommunityContext: () => CStarCommunityContext,
   CStarCommunityProvider: () => CStarCommunityProvider,
+  CStarDashboardProvider: () => CStarDashboardProvider,
   CStarLibraryContext: () => CStarLibraryContext,
   CStarLibraryProvider: () => CStarLibraryProvider,
   useArticle: () => useArticle,
   useArticleSearch: () => useArticleSearch,
   useArticles: () => useArticles,
+  useBossBattle: () => useBossBattle,
+  useCStarEvents: () => useCStarEvents,
+  useCStarMutation: () => useCStarMutation,
+  useCStarQuery: () => useCStarQuery,
   useCategories: () => useCategories,
   useChat: () => useChat,
   useChatClient: () => useChatClient,
   useCommunityClient: () => useCommunityClient,
   useCommunitySearch: () => useCommunitySearch,
   useConversations: () => useConversations,
+  useDashboardClient: () => useDashboardClient,
+  useGameActivity: () => useGameActivity,
+  useLeaderboard: () => useLeaderboard,
   useLibraryClient: () => useLibraryClient,
   useMessages: () => useMessages,
+  usePlayerStats: () => usePlayerStats,
   usePost: () => usePost,
   usePosts: () => usePosts,
   useTopics: () => useTopics,
@@ -664,25 +673,322 @@ function useCommunitySearch() {
   );
   return { results, isLoading, error, search };
 }
+
+// src/dashboard/CStarDashboardProvider.tsx
+var import_react17 = require("react");
+var import_jsx_runtime4 = require("react/jsx-runtime");
+var CStarDashboardContext = (0, import_react17.createContext)(null);
+function CStarDashboardProvider({ client, children }) {
+  const contextValue = (0, import_react17.useRef)({ client }).current;
+  (0, import_react17.useEffect)(() => {
+    return () => {
+      client.realtime.disconnect();
+    };
+  }, [client]);
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(CStarDashboardContext.Provider, { value: contextValue, children });
+}
+function useDashboardClient() {
+  const ctx = (0, import_react17.useContext)(CStarDashboardContext);
+  if (!ctx) {
+    throw new Error("useDashboardClient must be used within a <CStarDashboardProvider>");
+  }
+  return ctx.client;
+}
+
+// src/dashboard/useCStarQuery.ts
+var import_react18 = require("react");
+function resolveResource(client, path) {
+  const parts = path.split(".");
+  if (parts.length < 2 || parts[1] !== "list") return null;
+  const resourceName = parts[0];
+  const resource = client[resourceName];
+  if (!resource || typeof resource !== "object") return null;
+  const typed = resource;
+  if (typeof typed.list !== "function" || typeof typed.subscribe !== "function") return null;
+  return { resource, basePath: `/${resourceName}` };
+}
+function useCStarQuery(resource, params) {
+  const client = useDashboardClient();
+  const [data, setData] = (0, import_react18.useState)(null);
+  const [loading, setLoading] = (0, import_react18.useState)(true);
+  const [error, setError] = (0, import_react18.useState)(null);
+  const subscriptionRef = (0, import_react18.useRef)(null);
+  const paramsKey = params ? JSON.stringify(params) : "";
+  (0, import_react18.useEffect)(() => {
+    const resolved = resolveResource(client, resource);
+    if (!resolved) {
+      setError(new Error(`Invalid resource path: ${resource}. Expected format: 'tickets.list'`));
+      setLoading(false);
+      return;
+    }
+    const sub = resolved.resource.subscribe(client.realtime, params);
+    subscriptionRef.current = sub;
+    sub.on("change", (newData) => {
+      setData(newData);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subscriptionRef.current = null;
+    };
+  }, [client, resource, paramsKey]);
+  const refresh = (0, import_react18.useCallback)(async () => {
+    if (subscriptionRef.current) {
+      await subscriptionRef.current.refresh();
+    }
+  }, []);
+  return { data, loading, error, refresh };
+}
+
+// src/dashboard/useCStarMutation.ts
+var import_react19 = require("react");
+function resolveMutation(client, path) {
+  const parts = path.split(".");
+  if (parts.length < 2) return null;
+  const resourceName = parts[0];
+  const methodName = parts[1];
+  const resource = client[resourceName];
+  if (!resource || typeof resource !== "object") return null;
+  const method = resource[methodName];
+  if (typeof method !== "function") return null;
+  if (methodName === "update") {
+    return (params) => {
+      const p = params;
+      const { id, ...rest } = p;
+      return method.call(resource, id, rest);
+    };
+  }
+  if (methodName === "del" || methodName === "delete") {
+    return (params) => {
+      const p = params;
+      return method.call(resource, p.id);
+    };
+  }
+  return (params) => method.call(resource, params);
+}
+function useCStarMutation(resource) {
+  const client = useDashboardClient();
+  const [loading, setLoading] = (0, import_react19.useState)(false);
+  const [error, setError] = (0, import_react19.useState)(null);
+  const mutate = (0, import_react19.useCallback)(
+    async (params) => {
+      const fn = resolveMutation(client, resource);
+      if (!fn) {
+        throw new Error(`Invalid mutation path: ${resource}. Expected format: 'tickets.create'`);
+      }
+      setLoading(true);
+      setError(null);
+      try {
+        const result = await fn(params);
+        setLoading(false);
+        return result;
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        setError(error2);
+        setLoading(false);
+        throw error2;
+      }
+    },
+    [client, resource]
+  );
+  return { mutate, loading, error };
+}
+
+// src/dashboard/useCStarEvents.ts
+var import_react20 = require("react");
+var MAX_EVENTS = 100;
+function useCStarEvents(types) {
+  const client = useDashboardClient();
+  const [events, setEvents] = (0, import_react20.useState)([]);
+  const [connected, setConnected] = (0, import_react20.useState)(false);
+  const typesKey = types ? types.join(",") : "";
+  (0, import_react20.useEffect)(() => {
+    const realtime = client.realtime;
+    const handler = (event) => {
+      if (types && types.length > 0) {
+        const matches = types.some((pattern) => {
+          if (pattern.endsWith(".*")) {
+            return event.type.startsWith(pattern.slice(0, -2) + ".");
+          }
+          return event.type === pattern;
+        });
+        if (!matches) return;
+      }
+      setEvents((prev) => [event, ...prev].slice(0, MAX_EVENTS));
+    };
+    const connHandler = (isConnected) => {
+      setConnected(isConnected);
+    };
+    realtime.onAny(handler);
+    realtime.onConnectionChange(connHandler);
+    if (!realtime.connected) {
+      realtime.connect();
+    }
+    setConnected(realtime.connected);
+    return () => {
+      realtime.offAny(handler);
+      realtime.offConnectionChange(connHandler);
+    };
+  }, [client, typesKey]);
+  return { events, connected };
+}
+
+// src/dashboard/useBossBattle.ts
+var import_react21 = require("react");
+function useBossBattle() {
+  const client = useDashboardClient();
+  const [boss, setBoss] = (0, import_react21.useState)(null);
+  const [loading, setLoading] = (0, import_react21.useState)(true);
+  const [error, setError] = (0, import_react21.useState)(null);
+  const subRef = (0, import_react21.useRef)(null);
+  (0, import_react21.useEffect)(() => {
+    const sub = client.game.subscribeBoss(client.realtime);
+    subRef.current = sub;
+    sub.on("change", (data) => {
+      setBoss(data.length > 0 ? data[0] : null);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subRef.current = null;
+    };
+  }, [client]);
+  const refresh = (0, import_react21.useCallback)(async () => {
+    if (subRef.current) await subRef.current.refresh();
+  }, []);
+  return { boss, active: boss?.active ?? false, loading, error, refresh };
+}
+
+// src/dashboard/usePlayerStats.ts
+var import_react22 = require("react");
+function usePlayerStats(memberId) {
+  const client = useDashboardClient();
+  const [player, setPlayer] = (0, import_react22.useState)(null);
+  const [loading, setLoading] = (0, import_react22.useState)(true);
+  const [error, setError] = (0, import_react22.useState)(null);
+  const subRef = (0, import_react22.useRef)(null);
+  (0, import_react22.useEffect)(() => {
+    const sub = client.game.subscribePlayer(client.realtime, memberId);
+    subRef.current = sub;
+    sub.on("change", (data) => {
+      setPlayer(data.length > 0 ? data[0] : null);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subRef.current = null;
+    };
+  }, [client, memberId]);
+  const refresh = (0, import_react22.useCallback)(async () => {
+    if (subRef.current) await subRef.current.refresh();
+  }, []);
+  return { player, loading, error, refresh };
+}
+
+// src/dashboard/useLeaderboard.ts
+var import_react23 = require("react");
+function useLeaderboard(period) {
+  const client = useDashboardClient();
+  const [entries, setEntries] = (0, import_react23.useState)([]);
+  const [loading, setLoading] = (0, import_react23.useState)(true);
+  const [error, setError] = (0, import_react23.useState)(null);
+  const subRef = (0, import_react23.useRef)(null);
+  (0, import_react23.useEffect)(() => {
+    const sub = client.game.subscribeLeaderboard(client.realtime, period ? { period } : void 0);
+    subRef.current = sub;
+    sub.on("change", (data) => {
+      setEntries(data);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subRef.current = null;
+    };
+  }, [client, period]);
+  const refresh = (0, import_react23.useCallback)(async () => {
+    if (subRef.current) await subRef.current.refresh();
+  }, []);
+  return { entries, loading, error, refresh };
+}
+
+// src/dashboard/useGameActivity.ts
+var import_react24 = require("react");
+function useGameActivity() {
+  const client = useDashboardClient();
+  const [events, setEvents] = (0, import_react24.useState)([]);
+  const [loading, setLoading] = (0, import_react24.useState)(true);
+  const [error, setError] = (0, import_react24.useState)(null);
+  const subRef = (0, import_react24.useRef)(null);
+  (0, import_react24.useEffect)(() => {
+    const sub = client.game.subscribeActivity(client.realtime);
+    subRef.current = sub;
+    sub.on("change", (data) => {
+      setEvents(data);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subRef.current = null;
+    };
+  }, [client]);
+  const refresh = (0, import_react24.useCallback)(async () => {
+    if (subRef.current) await subRef.current.refresh();
+  }, []);
+  return { events, loading, error, refresh };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CStarChatContext,
   CStarChatProvider,
   CStarCommunityContext,
   CStarCommunityProvider,
+  CStarDashboardProvider,
   CStarLibraryContext,
   CStarLibraryProvider,
   useArticle,
   useArticleSearch,
   useArticles,
+  useBossBattle,
+  useCStarEvents,
+  useCStarMutation,
+  useCStarQuery,
   useCategories,
   useChat,
   useChatClient,
   useCommunityClient,
   useCommunitySearch,
   useConversations,
+  useDashboardClient,
+  useGameActivity,
+  useLeaderboard,
   useLibraryClient,
   useMessages,
+  usePlayerStats,
   usePost,
   usePosts,
   useTopics,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import react__default, { ReactNode } from 'react';
 import { ChatClient, ChatConfig, IdentifyParams, IdentifyResult, Conversation, ConversationCreateParams, WidgetMessage } from '@cstar.help/js/chat';
 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';
@@ -7,6 +7,7 @@ export { Category, LibraryArticle, LibraryArticleListParams, LibraryConfig, Libr
 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';
+import { CStarClient, RealtimeEvent, Boss, Player, LeaderboardEntry } from '@cstar.help/js';
 
 declare const CStarChatContext: react.Context<ChatClient | null>;
 declare const CStarLibraryContext: react.Context<LibraryClient | null>;
@@ -320,4 +321,160 @@ interface UseCommunitySearchReturn {
  */
 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 };
+interface CStarDashboardProviderProps {
+    /** A pre-configured CStarClient instance (server-side, secret key). */
+    client: CStarClient;
+    children: react__default.ReactNode;
+}
+/**
+ * Provides a CStarClient to dashboard hooks.
+ *
+ * Unlike `CStarChatProvider` (which uses a publishable key for customer-facing
+ * chat), this provider wraps a full admin client with a secret key for building
+ * custom dashboards.
+ *
+ * ```tsx
+ * const client = new CStarClient({ apiKey: 'sk_test_...', teamId: '...' });
+ *
+ * <CStarDashboardProvider client={client}>
+ *   <TicketList />
+ * </CStarDashboardProvider>
+ * ```
+ */
+declare function CStarDashboardProvider({ client, children }: CStarDashboardProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the CStarClient from the nearest CStarDashboardProvider.
+ * Throws if used outside a provider.
+ */
+declare function useDashboardClient(): CStarClient;
+
+interface UseCStarQueryReturn<T> {
+    /** Current data (auto-updated via SSE). Null until first fetch completes. */
+    data: T[] | null;
+    /** True during initial data fetch. */
+    loading: boolean;
+    /** Last error, if any. */
+    error: Error | null;
+    /** Manually refresh data from the server. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to a real-time resource query. Data auto-updates via SSE.
+ *
+ * ```tsx
+ * const { data: tickets, loading } = useCStarQuery('tickets.list', { status: 'open' });
+ * ```
+ *
+ * @param resource - Dot-path resource method (e.g., 'tickets.list', 'customers.list')
+ * @param params - Optional filter/pagination params
+ */
+declare function useCStarQuery<T = unknown>(resource: string, params?: Record<string, unknown>): UseCStarQueryReturn<T>;
+
+interface UseCStarMutationReturn<TParams, TResult> {
+    /** Execute the mutation. */
+    mutate: (params: TParams) => Promise<TResult>;
+    /** True while the mutation is in flight. */
+    loading: boolean;
+    /** Last error, if any. */
+    error: Error | null;
+}
+/**
+ * Create a mutation function for a resource method.
+ *
+ * ```tsx
+ * const { mutate: createTicket, loading } = useCStarMutation('tickets.create');
+ * await createTicket({ title: 'New ticket', customerId: 'cus_123' });
+ * ```
+ *
+ * @param resource - Dot-path resource method (e.g., 'tickets.create', 'tickets.update')
+ */
+declare function useCStarMutation<TParams = Record<string, unknown>, TResult = unknown>(resource: string): UseCStarMutationReturn<TParams, TResult>;
+
+interface UseCStarEventsReturn {
+    /** Rolling buffer of recent events (newest first). */
+    events: RealtimeEvent[];
+    /** Whether the SSE connection is active. */
+    connected: boolean;
+}
+/**
+ * Access the raw SSE event stream for custom real-time UIs.
+ *
+ * ```tsx
+ * const { events, connected } = useCStarEvents(['boss.*', 'achievement.*']);
+ * ```
+ *
+ * @param types - Optional event type filter (supports wildcards)
+ */
+declare function useCStarEvents(types?: string[]): UseCStarEventsReturn;
+
+interface UseBossBattleReturn {
+    /** Current boss state (null if no boss active or loading). */
+    boss: Boss | null;
+    /** Whether a boss is currently active. */
+    active: boolean;
+    /** True during initial data fetch. */
+    loading: boolean;
+    /** Last error, if any. */
+    error: Error | null;
+    /** Manually refresh boss data. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to live boss battle state.
+ *
+ * ```tsx
+ * const { boss, active, loading, error } = useBossBattle();
+ * if (active) {
+ *   return <BossHPBar hp={boss.health} max={boss.maxHealth} />;
+ * }
+ * ```
+ */
+declare function useBossBattle(): UseBossBattleReturn;
+
+interface UsePlayerStatsReturn {
+    player: Player | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to player stats (XP, level, streaks).
+ *
+ * ```tsx
+ * const { player, loading, error } = usePlayerStats('user_123');
+ * ```
+ */
+declare function usePlayerStats(memberId?: string): UsePlayerStatsReturn;
+
+interface UseLeaderboardReturn {
+    entries: LeaderboardEntry[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to team leaderboard rankings.
+ *
+ * ```tsx
+ * const { entries, loading, error } = useLeaderboard('weekly');
+ * ```
+ */
+declare function useLeaderboard(period?: 'daily' | 'weekly' | 'allTime'): UseLeaderboardReturn;
+
+interface UseGameActivityReturn {
+    /** Rolling feed of recent game events. */
+    events: Record<string, unknown>[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to the team game activity feed (achievements, boss defeats, level ups).
+ *
+ * ```tsx
+ * const { events, loading } = useGameActivity();
+ * ```
+ */
+declare function useGameActivity(): UseGameActivityReturn;
+
+export { CStarChatContext, CStarChatProvider, type CStarChatProviderProps, CStarCommunityContext, CStarCommunityProvider, type CStarCommunityProviderProps, CStarDashboardProvider, type CStarDashboardProviderProps, CStarLibraryContext, CStarLibraryProvider, type CStarLibraryProviderProps, type TypingAgent, type UseArticleReturn, type UseArticleSearchReturn, type UseArticlesReturn, type UseBossBattleReturn, type UseCStarEventsReturn, type UseCStarMutationReturn, type UseCStarQueryReturn, type UseCategoriesReturn, type UseChatReturn, type UseCommunitySearchReturn, type UseConversationsReturn, type UseGameActivityReturn, type UseLeaderboardReturn, type UseMessagesReturn, type UsePlayerStatsReturn, type UsePostReturn, type UsePostsReturn, type UseTopicsReturn, type UseTypingReturn, useArticle, useArticleSearch, useArticles, useBossBattle, useCStarEvents, useCStarMutation, useCStarQuery, useCategories, useChat, useChatClient, useCommunityClient, useCommunitySearch, useConversations, useDashboardClient, useGameActivity, useLeaderboard, useLibraryClient, useMessages, usePlayerStats, usePost, usePosts, useTopics, useTyping };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import react__default, { ReactNode } from 'react';
 import { ChatClient, ChatConfig, IdentifyParams, IdentifyResult, Conversation, ConversationCreateParams, WidgetMessage } from '@cstar.help/js/chat';
 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';
@@ -7,6 +7,7 @@ export { Category, LibraryArticle, LibraryArticleListParams, LibraryConfig, Libr
 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';
+import { CStarClient, RealtimeEvent, Boss, Player, LeaderboardEntry } from '@cstar.help/js';
 
 declare const CStarChatContext: react.Context<ChatClient | null>;
 declare const CStarLibraryContext: react.Context<LibraryClient | null>;
@@ -320,4 +321,160 @@ interface UseCommunitySearchReturn {
  */
 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 };
+interface CStarDashboardProviderProps {
+    /** A pre-configured CStarClient instance (server-side, secret key). */
+    client: CStarClient;
+    children: react__default.ReactNode;
+}
+/**
+ * Provides a CStarClient to dashboard hooks.
+ *
+ * Unlike `CStarChatProvider` (which uses a publishable key for customer-facing
+ * chat), this provider wraps a full admin client with a secret key for building
+ * custom dashboards.
+ *
+ * ```tsx
+ * const client = new CStarClient({ apiKey: 'sk_test_...', teamId: '...' });
+ *
+ * <CStarDashboardProvider client={client}>
+ *   <TicketList />
+ * </CStarDashboardProvider>
+ * ```
+ */
+declare function CStarDashboardProvider({ client, children }: CStarDashboardProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the CStarClient from the nearest CStarDashboardProvider.
+ * Throws if used outside a provider.
+ */
+declare function useDashboardClient(): CStarClient;
+
+interface UseCStarQueryReturn<T> {
+    /** Current data (auto-updated via SSE). Null until first fetch completes. */
+    data: T[] | null;
+    /** True during initial data fetch. */
+    loading: boolean;
+    /** Last error, if any. */
+    error: Error | null;
+    /** Manually refresh data from the server. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to a real-time resource query. Data auto-updates via SSE.
+ *
+ * ```tsx
+ * const { data: tickets, loading } = useCStarQuery('tickets.list', { status: 'open' });
+ * ```
+ *
+ * @param resource - Dot-path resource method (e.g., 'tickets.list', 'customers.list')
+ * @param params - Optional filter/pagination params
+ */
+declare function useCStarQuery<T = unknown>(resource: string, params?: Record<string, unknown>): UseCStarQueryReturn<T>;
+
+interface UseCStarMutationReturn<TParams, TResult> {
+    /** Execute the mutation. */
+    mutate: (params: TParams) => Promise<TResult>;
+    /** True while the mutation is in flight. */
+    loading: boolean;
+    /** Last error, if any. */
+    error: Error | null;
+}
+/**
+ * Create a mutation function for a resource method.
+ *
+ * ```tsx
+ * const { mutate: createTicket, loading } = useCStarMutation('tickets.create');
+ * await createTicket({ title: 'New ticket', customerId: 'cus_123' });
+ * ```
+ *
+ * @param resource - Dot-path resource method (e.g., 'tickets.create', 'tickets.update')
+ */
+declare function useCStarMutation<TParams = Record<string, unknown>, TResult = unknown>(resource: string): UseCStarMutationReturn<TParams, TResult>;
+
+interface UseCStarEventsReturn {
+    /** Rolling buffer of recent events (newest first). */
+    events: RealtimeEvent[];
+    /** Whether the SSE connection is active. */
+    connected: boolean;
+}
+/**
+ * Access the raw SSE event stream for custom real-time UIs.
+ *
+ * ```tsx
+ * const { events, connected } = useCStarEvents(['boss.*', 'achievement.*']);
+ * ```
+ *
+ * @param types - Optional event type filter (supports wildcards)
+ */
+declare function useCStarEvents(types?: string[]): UseCStarEventsReturn;
+
+interface UseBossBattleReturn {
+    /** Current boss state (null if no boss active or loading). */
+    boss: Boss | null;
+    /** Whether a boss is currently active. */
+    active: boolean;
+    /** True during initial data fetch. */
+    loading: boolean;
+    /** Last error, if any. */
+    error: Error | null;
+    /** Manually refresh boss data. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to live boss battle state.
+ *
+ * ```tsx
+ * const { boss, active, loading, error } = useBossBattle();
+ * if (active) {
+ *   return <BossHPBar hp={boss.health} max={boss.maxHealth} />;
+ * }
+ * ```
+ */
+declare function useBossBattle(): UseBossBattleReturn;
+
+interface UsePlayerStatsReturn {
+    player: Player | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to player stats (XP, level, streaks).
+ *
+ * ```tsx
+ * const { player, loading, error } = usePlayerStats('user_123');
+ * ```
+ */
+declare function usePlayerStats(memberId?: string): UsePlayerStatsReturn;
+
+interface UseLeaderboardReturn {
+    entries: LeaderboardEntry[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to team leaderboard rankings.
+ *
+ * ```tsx
+ * const { entries, loading, error } = useLeaderboard('weekly');
+ * ```
+ */
+declare function useLeaderboard(period?: 'daily' | 'weekly' | 'allTime'): UseLeaderboardReturn;
+
+interface UseGameActivityReturn {
+    /** Rolling feed of recent game events. */
+    events: Record<string, unknown>[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Subscribe to the team game activity feed (achievements, boss defeats, level ups).
+ *
+ * ```tsx
+ * const { events, loading } = useGameActivity();
+ * ```
+ */
+declare function useGameActivity(): UseGameActivityReturn;
+
+export { CStarChatContext, CStarChatProvider, type CStarChatProviderProps, CStarCommunityContext, CStarCommunityProvider, type CStarCommunityProviderProps, CStarDashboardProvider, type CStarDashboardProviderProps, CStarLibraryContext, CStarLibraryProvider, type CStarLibraryProviderProps, type TypingAgent, type UseArticleReturn, type UseArticleSearchReturn, type UseArticlesReturn, type UseBossBattleReturn, type UseCStarEventsReturn, type UseCStarMutationReturn, type UseCStarQueryReturn, type UseCategoriesReturn, type UseChatReturn, type UseCommunitySearchReturn, type UseConversationsReturn, type UseGameActivityReturn, type UseLeaderboardReturn, type UseMessagesReturn, type UsePlayerStatsReturn, type UsePostReturn, type UsePostsReturn, type UseTopicsReturn, type UseTypingReturn, useArticle, useArticleSearch, useArticles, useBossBattle, useCStarEvents, useCStarMutation, useCStarQuery, useCategories, useChat, useChatClient, useCommunityClient, useCommunitySearch, useConversations, useDashboardClient, useGameActivity, useLeaderboard, useLibraryClient, useMessages, usePlayerStats, usePost, usePosts, useTopics, useTyping };

package/dist/index.js

@@ -618,24 +618,321 @@ function useCommunitySearch() {
   );
   return { results, isLoading, error, search };
 }
+
+// src/dashboard/CStarDashboardProvider.tsx
+import { createContext as createContext2, useContext as useContext2, useEffect as useEffect13, useRef as useRef15 } from "react";
+import { jsx as jsx4 } from "react/jsx-runtime";
+var CStarDashboardContext = createContext2(null);
+function CStarDashboardProvider({ client, children }) {
+  const contextValue = useRef15({ client }).current;
+  useEffect13(() => {
+    return () => {
+      client.realtime.disconnect();
+    };
+  }, [client]);
+  return /* @__PURE__ */ jsx4(CStarDashboardContext.Provider, { value: contextValue, children });
+}
+function useDashboardClient() {
+  const ctx = useContext2(CStarDashboardContext);
+  if (!ctx) {
+    throw new Error("useDashboardClient must be used within a <CStarDashboardProvider>");
+  }
+  return ctx.client;
+}
+
+// src/dashboard/useCStarQuery.ts
+import { useState as useState13, useEffect as useEffect14, useRef as useRef16, useCallback as useCallback12 } from "react";
+function resolveResource(client, path) {
+  const parts = path.split(".");
+  if (parts.length < 2 || parts[1] !== "list") return null;
+  const resourceName = parts[0];
+  const resource = client[resourceName];
+  if (!resource || typeof resource !== "object") return null;
+  const typed = resource;
+  if (typeof typed.list !== "function" || typeof typed.subscribe !== "function") return null;
+  return { resource, basePath: `/${resourceName}` };
+}
+function useCStarQuery(resource, params) {
+  const client = useDashboardClient();
+  const [data, setData] = useState13(null);
+  const [loading, setLoading] = useState13(true);
+  const [error, setError] = useState13(null);
+  const subscriptionRef = useRef16(null);
+  const paramsKey = params ? JSON.stringify(params) : "";
+  useEffect14(() => {
+    const resolved = resolveResource(client, resource);
+    if (!resolved) {
+      setError(new Error(`Invalid resource path: ${resource}. Expected format: 'tickets.list'`));
+      setLoading(false);
+      return;
+    }
+    const sub = resolved.resource.subscribe(client.realtime, params);
+    subscriptionRef.current = sub;
+    sub.on("change", (newData) => {
+      setData(newData);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subscriptionRef.current = null;
+    };
+  }, [client, resource, paramsKey]);
+  const refresh = useCallback12(async () => {
+    if (subscriptionRef.current) {
+      await subscriptionRef.current.refresh();
+    }
+  }, []);
+  return { data, loading, error, refresh };
+}
+
+// src/dashboard/useCStarMutation.ts
+import { useState as useState14, useCallback as useCallback13 } from "react";
+function resolveMutation(client, path) {
+  const parts = path.split(".");
+  if (parts.length < 2) return null;
+  const resourceName = parts[0];
+  const methodName = parts[1];
+  const resource = client[resourceName];
+  if (!resource || typeof resource !== "object") return null;
+  const method = resource[methodName];
+  if (typeof method !== "function") return null;
+  if (methodName === "update") {
+    return (params) => {
+      const p = params;
+      const { id, ...rest } = p;
+      return method.call(resource, id, rest);
+    };
+  }
+  if (methodName === "del" || methodName === "delete") {
+    return (params) => {
+      const p = params;
+      return method.call(resource, p.id);
+    };
+  }
+  return (params) => method.call(resource, params);
+}
+function useCStarMutation(resource) {
+  const client = useDashboardClient();
+  const [loading, setLoading] = useState14(false);
+  const [error, setError] = useState14(null);
+  const mutate = useCallback13(
+    async (params) => {
+      const fn = resolveMutation(client, resource);
+      if (!fn) {
+        throw new Error(`Invalid mutation path: ${resource}. Expected format: 'tickets.create'`);
+      }
+      setLoading(true);
+      setError(null);
+      try {
+        const result = await fn(params);
+        setLoading(false);
+        return result;
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        setError(error2);
+        setLoading(false);
+        throw error2;
+      }
+    },
+    [client, resource]
+  );
+  return { mutate, loading, error };
+}
+
+// src/dashboard/useCStarEvents.ts
+import { useState as useState15, useEffect as useEffect15 } from "react";
+var MAX_EVENTS = 100;
+function useCStarEvents(types) {
+  const client = useDashboardClient();
+  const [events, setEvents] = useState15([]);
+  const [connected, setConnected] = useState15(false);
+  const typesKey = types ? types.join(",") : "";
+  useEffect15(() => {
+    const realtime = client.realtime;
+    const handler = (event) => {
+      if (types && types.length > 0) {
+        const matches = types.some((pattern) => {
+          if (pattern.endsWith(".*")) {
+            return event.type.startsWith(pattern.slice(0, -2) + ".");
+          }
+          return event.type === pattern;
+        });
+        if (!matches) return;
+      }
+      setEvents((prev) => [event, ...prev].slice(0, MAX_EVENTS));
+    };
+    const connHandler = (isConnected) => {
+      setConnected(isConnected);
+    };
+    realtime.onAny(handler);
+    realtime.onConnectionChange(connHandler);
+    if (!realtime.connected) {
+      realtime.connect();
+    }
+    setConnected(realtime.connected);
+    return () => {
+      realtime.offAny(handler);
+      realtime.offConnectionChange(connHandler);
+    };
+  }, [client, typesKey]);
+  return { events, connected };
+}
+
+// src/dashboard/useBossBattle.ts
+import { useState as useState16, useEffect as useEffect16, useRef as useRef17, useCallback as useCallback14 } from "react";
+function useBossBattle() {
+  const client = useDashboardClient();
+  const [boss, setBoss] = useState16(null);
+  const [loading, setLoading] = useState16(true);
+  const [error, setError] = useState16(null);
+  const subRef = useRef17(null);
+  useEffect16(() => {
+    const sub = client.game.subscribeBoss(client.realtime);
+    subRef.current = sub;
+    sub.on("change", (data) => {
+      setBoss(data.length > 0 ? data[0] : null);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subRef.current = null;
+    };
+  }, [client]);
+  const refresh = useCallback14(async () => {
+    if (subRef.current) await subRef.current.refresh();
+  }, []);
+  return { boss, active: boss?.active ?? false, loading, error, refresh };
+}
+
+// src/dashboard/usePlayerStats.ts
+import { useState as useState17, useEffect as useEffect17, useRef as useRef18, useCallback as useCallback15 } from "react";
+function usePlayerStats(memberId) {
+  const client = useDashboardClient();
+  const [player, setPlayer] = useState17(null);
+  const [loading, setLoading] = useState17(true);
+  const [error, setError] = useState17(null);
+  const subRef = useRef18(null);
+  useEffect17(() => {
+    const sub = client.game.subscribePlayer(client.realtime, memberId);
+    subRef.current = sub;
+    sub.on("change", (data) => {
+      setPlayer(data.length > 0 ? data[0] : null);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subRef.current = null;
+    };
+  }, [client, memberId]);
+  const refresh = useCallback15(async () => {
+    if (subRef.current) await subRef.current.refresh();
+  }, []);
+  return { player, loading, error, refresh };
+}
+
+// src/dashboard/useLeaderboard.ts
+import { useState as useState18, useEffect as useEffect18, useRef as useRef19, useCallback as useCallback16 } from "react";
+function useLeaderboard(period) {
+  const client = useDashboardClient();
+  const [entries, setEntries] = useState18([]);
+  const [loading, setLoading] = useState18(true);
+  const [error, setError] = useState18(null);
+  const subRef = useRef19(null);
+  useEffect18(() => {
+    const sub = client.game.subscribeLeaderboard(client.realtime, period ? { period } : void 0);
+    subRef.current = sub;
+    sub.on("change", (data) => {
+      setEntries(data);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subRef.current = null;
+    };
+  }, [client, period]);
+  const refresh = useCallback16(async () => {
+    if (subRef.current) await subRef.current.refresh();
+  }, []);
+  return { entries, loading, error, refresh };
+}
+
+// src/dashboard/useGameActivity.ts
+import { useState as useState19, useEffect as useEffect19, useRef as useRef20, useCallback as useCallback17 } from "react";
+function useGameActivity() {
+  const client = useDashboardClient();
+  const [events, setEvents] = useState19([]);
+  const [loading, setLoading] = useState19(true);
+  const [error, setError] = useState19(null);
+  const subRef = useRef20(null);
+  useEffect19(() => {
+    const sub = client.game.subscribeActivity(client.realtime);
+    subRef.current = sub;
+    sub.on("change", (data) => {
+      setEvents(data);
+      setLoading(false);
+      setError(null);
+    });
+    sub.on("error", (err) => {
+      setError(err);
+      setLoading(false);
+    });
+    return () => {
+      sub.unsubscribe();
+      subRef.current = null;
+    };
+  }, [client]);
+  const refresh = useCallback17(async () => {
+    if (subRef.current) await subRef.current.refresh();
+  }, []);
+  return { events, loading, error, refresh };
+}
 export {
   CStarChatContext,
   CStarChatProvider,
   CStarCommunityContext,
   CStarCommunityProvider,
+  CStarDashboardProvider,
   CStarLibraryContext,
   CStarLibraryProvider,
   useArticle,
   useArticleSearch,
   useArticles,
+  useBossBattle,
+  useCStarEvents,
+  useCStarMutation,
+  useCStarQuery,
   useCategories,
   useChat,
   useChatClient,
   useCommunityClient,
   useCommunitySearch,
   useConversations,
+  useDashboardClient,
+  useGameActivity,
+  useLeaderboard,
   useLibraryClient,
   useMessages,
+  usePlayerStats,
   usePost,
   usePosts,
   useTopics,

package/package.json

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