@tribe-nest/forge 1.13.0

package/src/data/queries/useAuthActions.ts

@@ -0,0 +1,28 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation } from "@tanstack/react-query";
+
+// Stateless account actions (no session state) — kept out of PublicAuthContext.
+
+/** Request a password-reset email. */
+export function useForgotPassword() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { email: string; origin?: string }>({
+    mutationFn: async ({ email, origin }) => {
+      const res = await client.post("/public/accounts/forgot-password", { email, origin });
+      return res.data;
+    },
+  });
+}
+
+/** Complete a password reset with the emailed token. */
+export function useResetPassword() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { token: string; password: string }>({
+    mutationFn: async ({ token, password }) => {
+      const res = await client.post("/public/accounts/reset-password", { token, password });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useBlog.ts

@@ -0,0 +1,103 @@
+import type { BlogPost, BlogCategory, PaginatedData } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+/** The single featured blog post for the profile (null if none). */
+export function useFeaturedBlogPost() {
+  const { client, profileId } = useForge();
+
+  return useQuery<BlogPost | null>({
+    queryKey: ["featured-blog-post", profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/blog/posts/featured`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+export interface GetBlogPostsParams {
+  page?: number;
+  limit?: number;
+}
+
+/** Paginated published blog posts for the profile. */
+export function useBlogPosts(params?: GetBlogPostsParams) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<BlogPost>>({
+    queryKey: ["blog-posts", profileId, params?.page ?? 1, params?.limit ?? 10],
+    queryFn: async () => {
+      const res = await client.get(`/public/blog/posts`, {
+        params: {
+          profileId,
+          page: params?.page ?? 1,
+          limit: params?.limit ?? 10,
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** A single blog post by id. */
+export function useBlogPost(postId?: string, options?: { initialData?: BlogPost | null }) {
+  const { client, profileId } = useForge();
+
+  return useQuery<BlogPost | null>({
+    queryKey: ["blog-post", profileId, postId],
+    queryFn: async () => {
+      const res = await client.get(`/public/blog/posts/${postId}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!postId,
+    initialData: options?.initialData,
+  });
+}
+
+/** A blog category by slug. */
+export function useBlogCategory(slug?: string, options?: { initialData?: BlogCategory | null }) {
+  const { client, profileId } = useForge();
+
+  return useQuery<BlogCategory | null>({
+    queryKey: ["blog-category-public", profileId, slug],
+    queryFn: async () => {
+      const res = await client.get(`/public/blog/posts/categories/${slug}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!slug,
+    initialData: options?.initialData,
+  });
+}
+
+export interface GetBlogCategoryPostsParams {
+  page?: number;
+  limit?: number;
+}
+
+/** Paginated posts within a blog category. */
+export function useBlogCategoryPosts(slug?: string, params?: GetBlogCategoryPostsParams) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<BlogPost>>({
+    queryKey: ["blog-category-posts-public", profileId, slug, params?.page ?? 1, params?.limit ?? 12],
+    queryFn: async () => {
+      const res = await client.get(`/public/blog/posts/categories/${slug}/posts`, {
+        params: {
+          profileId,
+          page: params?.page ?? 1,
+          limit: params?.limit ?? 12,
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!slug,
+  });
+}

package/src/data/queries/useBlogComments.ts

@@ -0,0 +1,96 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+export type BlogCommentReply = {
+  id: string;
+  content: string;
+  createdAt: string;
+  authorName: string | null;
+};
+
+export type BlogComment = {
+  id: string;
+  content: string;
+  createdAt: string;
+  authorName: string | null;
+  replies: BlogCommentReply[];
+};
+
+export type BlogCommentsPage = {
+  data: BlogComment[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasNextPage: boolean;
+  nextPage: number | null;
+};
+
+export type PublicBlogCommentSettings = {
+  enabled: boolean;
+  requireSignIn: boolean;
+};
+
+export type SubmitBlogCommentInput = {
+  blogPostId: string;
+  content: string;
+  guestName?: string;
+  guestEmail?: string;
+  // Bot protection (Altcha PoW token + honeypot), spread through to the API.
+  botToken?: string;
+  botField?: string;
+};
+
+export type SubmitBlogCommentResult = {
+  id: string;
+  status: "pending" | "published";
+  pending: boolean;
+};
+
+/** Whether the profile accepts comments + whether sign-in is required. */
+export function useBlogCommentSettings() {
+  const { client, profileId } = useForge();
+  return useQuery<PublicBlogCommentSettings>({
+    queryKey: ["blog-comment-settings", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/blog-comments/settings", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!client && !!profileId,
+  });
+}
+
+/** Paginated published comments (with nested published replies) for a post. */
+export function useBlogComments(blogPostId?: string, limit = 10) {
+  const { client, profileId } = useForge();
+  return useInfiniteQuery<BlogCommentsPage>({
+    queryKey: ["blog-comments", profileId, blogPostId, limit],
+    queryFn: async ({ pageParam }) => {
+      const res = await client.get("/public/blog-comments", {
+        params: { profileId, blogPostId, page: pageParam, limit },
+      });
+      return res.data;
+    },
+    initialPageParam: 1,
+    getNextPageParam: (last) => (last.hasNextPage ? (last.nextPage ?? last.page + 1) : undefined),
+    enabled: !!client && !!profileId && !!blogPostId,
+  });
+}
+
+/** Submit a comment. Signed-in callers send content only; anonymous callers
+ * also send name + email (when the profile allows anonymous comments). */
+export function useSubmitBlogComment() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation<SubmitBlogCommentResult, unknown, SubmitBlogCommentInput>({
+    mutationFn: async (body) => {
+      const res = await client.post("/public/blog-comments", { ...body, profileId });
+      return res.data;
+    },
+    onSuccess: (result, vars) => {
+      // Refresh the list only when the comment is immediately public.
+      if (!result.pending) {
+        queryClient.invalidateQueries({ queryKey: ["blog-comments", profileId, vars.blogPostId] });
+      }
+    },
+  });
+}

package/src/data/queries/useBroadcasts.ts

@@ -0,0 +1,31 @@
+import type { ILiveBroadcast, IBroadcastPass } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** Live broadcasts for the profile. */
+export function useLiveBroadcasts() {
+  const { client, profileId } = useForge();
+
+  return useQuery<ILiveBroadcast[]>({
+    queryKey: ["live-broadcasts", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/broadcasts", {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** Validate an event/broadcast pass (ticket code) to join a broadcast. */
+export function useValidateBroadcastPass() {
+  const { client } = useForge();
+
+  return useMutation<IBroadcastPass, unknown, { broadcastId: string; eventPassId: string; sessionId?: string }>({
+    mutationFn: async (payload) => {
+      const res = await client.post(`/public/events/validate-pass`, payload);
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useCertificates.ts

@@ -0,0 +1,58 @@
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+
+/** Public verification facts for an issued certificate (verify by code). */
+export type CertificateVerification = {
+  recipientName: string;
+  courseTitle: string | null;
+  issuedAt: string;
+  revokedAt: string | null;
+  revokedReason: string | null;
+  /** false when revoked. */
+  verified: boolean;
+};
+
+/** Short-lived signed URL to the certificate PDF (gated to the recipient). */
+export type CertificateDownload = {
+  pdfUrl: string;
+};
+
+/**
+ * Public, unauthenticated certificate verification by human-typable code.
+ * GET /public/quiz/certificates/verify/:code — returns recipient/course/issue
+ * facts + revoked status only (never the PDF or email). Fully public: no
+ * profileId gating, since a verification code is globally unique.
+ */
+export function useCertificateVerification(code?: string) {
+  const { client } = useForge();
+
+  return useQuery<CertificateVerification>({
+    queryKey: ["certificate-verify", code],
+    queryFn: async () => {
+      const res = await client.get(`/public/quiz/certificates/verify/${code}`);
+      return res.data;
+    },
+    enabled: !!client && !!code,
+    retry: false,
+  });
+}
+
+/**
+ * Fetch a short-lived signed download URL for an issued certificate PDF.
+ * GET /public/quiz/certificates/:id/download — gated server-side to the
+ * recipient (by authed session account OR the owning course_access id). The
+ * caller supplies the courseAccessId it enrolled under; the Bearer session
+ * (when present) is attached by the shared client.
+ */
+export function useCertificateDownload() {
+  const { client } = useForge();
+
+  return useMutation<CertificateDownload, unknown, { certificateId: string; courseAccessId?: string }>({
+    mutationFn: async ({ certificateId, courseAccessId }) => {
+      const res = await client.get(`/public/quiz/certificates/${certificateId}/download`, {
+        params: courseAccessId ? { courseAccessId } : undefined,
+      });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useChat.ts

@@ -0,0 +1,267 @@
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useRef, useState } from "react";
+import { io, type Socket } from "socket.io-client";
+import { useForge } from "../../provider/ForgeProvider";
+import { getForgeWebSocketUrl } from "../../client/createForgeClient";
+import { PUBLIC_ACCESS_TOKEN_KEY } from "../../contexts/PublicAuthContext";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export interface ChatChannel {
+  id: string;
+  name: string | null;
+  type: "public" | "private" | "dm";
+  description: string | null;
+  /** For DM channels, the counterpart participant (backend-enriched). */
+  otherParticipant?: ChatDmPeer | null;
+}
+
+export interface ChatAttachment {
+  url: string;
+  fileName: string;
+  fileSize: number;
+  fileType: string;
+}
+
+export interface ChatMessage {
+  id: string;
+  channelId: string;
+  content: string | null;
+  senderAccountId: string;
+  senderFirstName: string;
+  senderLastName: string;
+  isPinned: boolean;
+  attachments: ChatAttachment[];
+  parentMessageId: string | null;
+  replyCount: number;
+  lastReplyAt: string | null;
+  createdAt: string;
+}
+
+export interface ChatDmPeer {
+  accountId: string;
+  firstName: string | null;
+  lastName: string | null;
+  email: string;
+}
+
+export interface ChatDirectoryMember {
+  accountId: string;
+  firstName: string | null;
+  lastName: string | null;
+  email: string;
+  membershipTierId: string;
+}
+
+export interface ChatUnreadCount {
+  channelId: string;
+  unreadCount: number;
+}
+
+export interface ChatMessagesPage {
+  data: ChatMessage[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+// Query keys are exported so the realtime layer (and creators) can patch the
+// same caches the data hooks populate.
+export const chatKeys = {
+  channels: (profileId?: string) => ["public-chat-channels", profileId] as const,
+  messages: (channelId?: string) => ["public-chat-messages", channelId] as const,
+  pinned: (channelId?: string) => ["public-chat-pinned", channelId] as const,
+  unread: (profileId?: string) => ["public-chat-unread-counts", profileId] as const,
+  dm: (profileId?: string) => ["public-chat-dm", profileId] as const,
+  replies: (parentMessageId?: string) => ["public-chat-replies", parentMessageId] as const,
+  memberDirectory: (profileId?: string) => ["public-chat-member-directory", profileId] as const,
+};
+
+// ── Data hooks ───────────────────────────────────────────────────────────────
+
+/** Channels visible to the current member (GET /public/chat/channels). */
+export function useChatChannels() {
+  const { client, profileId } = useForge();
+  return useQuery<ChatChannel[]>({
+    queryKey: chatKeys.channels(profileId),
+    queryFn: async () => {
+      const res = await client.get("/public/chat/channels", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** Paginated messages for a channel, newest first (GET /public/chat/channels/:id/messages). */
+export function useChatMessages(channelId?: string, limit = 50) {
+  const { client, profileId } = useForge();
+  return useInfiniteQuery<ChatMessagesPage>({
+    queryKey: chatKeys.messages(channelId),
+    queryFn: async ({ pageParam = 1 }) => {
+      const res = await client.get(`/public/chat/channels/${channelId}/messages`, {
+        params: { profileId, page: pageParam, limit },
+      });
+      return res.data;
+    },
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) =>
+      lastPage.page * lastPage.limit < lastPage.total ? lastPage.page + 1 : undefined,
+    enabled: !!channelId && !!client && !!profileId,
+  });
+}
+
+/** Pinned messages for a channel (GET /public/chat/channels/:id/pinned). */
+export function useChatPinnedMessages(channelId?: string) {
+  const { client, profileId } = useForge();
+  return useQuery<ChatMessage[]>({
+    queryKey: chatKeys.pinned(channelId),
+    queryFn: async () => {
+      const res = await client.get(`/public/chat/channels/${channelId}/pinned`, { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!channelId && !!client && !!profileId,
+  });
+}
+
+/** Per-channel unread counts, polled every 30s (GET /public/chat/unread-counts). */
+export function useChatUnreadCounts() {
+  const { client, profileId } = useForge();
+  return useQuery<ChatUnreadCount[]>({
+    queryKey: chatKeys.unread(profileId),
+    queryFn: async () => {
+      const res = await client.get("/public/chat/unread-counts", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+    refetchInterval: 30000,
+  });
+}
+
+/** Mark messages as read (POST /public/chat/read-receipts); invalidates unread counts. */
+export function useMarkChatRead() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (messageIds: string[]) => {
+      if (messageIds.length === 0) return;
+      await client.post("/public/chat/read-receipts", { profileId, messageIds });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["public-chat-unread-counts"] });
+    },
+  });
+}
+
+/** Send a message over REST (POST /public/chat/messages). Realtime path uses the socket. */
+export function useSendChatMessage() {
+  const { client, profileId } = useForge();
+  return useMutation({
+    mutationFn: async (input: {
+      channelId: string;
+      content?: string;
+      attachments?: ChatAttachment[];
+      parentMessageId?: string;
+    }) => {
+      const res = await client.post("/public/chat/messages", { profileId, ...input });
+      return res.data as ChatMessage;
+    },
+  });
+}
+
+/** Paginated replies for a thread parent (GET /public/chat/messages/:id/replies), oldest first. */
+export function useChatMessageReplies(parentMessageId?: string, limit = 50) {
+  const { client, profileId } = useForge();
+  return useInfiniteQuery<ChatMessagesPage>({
+    queryKey: chatKeys.replies(parentMessageId),
+    queryFn: async ({ pageParam = 1 }) => {
+      const res = await client.get(`/public/chat/messages/${parentMessageId}/replies`, {
+        params: { profileId, page: pageParam, limit },
+      });
+      return res.data;
+    },
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) =>
+      lastPage.page * lastPage.limit < lastPage.total ? lastPage.page + 1 : undefined,
+    enabled: !!parentMessageId && !!client && !!profileId,
+  });
+}
+
+/** Same-tier members the current member may start a DM with (GET /public/chat/dm/directory). */
+export function useChatMemberDirectory() {
+  const { client, profileId } = useForge();
+  return useQuery<ChatDirectoryMember[]>({
+    queryKey: chatKeys.memberDirectory(profileId),
+    queryFn: async () => {
+      const res = await client.get("/public/chat/dm/directory", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** Open/create a DM with another member (POST /public/chat/dm/member). */
+export function useCreateMemberDm() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (targetAccountId: string) => {
+      const res = await client.post("/public/chat/dm/member", { profileId, targetAccountId });
+      return res.data as ChatChannel;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: chatKeys.channels(profileId) });
+    },
+  });
+}
+
+/** The current member's DM channel, if any (GET /public/chat/dm). */
+export function useChatDm() {
+  const { client, profileId } = useForge();
+  return useQuery<ChatChannel | null>({
+    queryKey: chatKeys.dm(profileId),
+    queryFn: async () => {
+      const res = await client.get("/public/chat/dm", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** Open/create the member's DM channel (POST /public/chat/dm). */
+export function useCreateChatDm() {
+  const { client, profileId } = useForge();
+  return useMutation({
+    mutationFn: async () => {
+      const res = await client.post("/public/chat/dm", { profileId });
+      return res.data as ChatChannel;
+    },
+  });
+}
+
+// ── Realtime primitive ───────────────────────────────────────────────────────
+
+/**
+ * Connects a socket.io client to the chat gateway and returns it once connected.
+ * Token is read from localStorage (`PUBLIC_ACCESS_TOKEN_KEY`). The socket is kept
+ * for the lifetime of the component so channel switches don't reconnect.
+ *
+ * Event/emit names match the backend gateway: emits `chatJoinChannel`,
+ * `chatLeaveChannel`, `chatSendMessage`, `chatTyping`; receives a `message`
+ * envelope with `event` in {chatNewMessage, chatUserTyping, chatMessagePinned}.
+ */
+export function useChatSocket(enabled: boolean) {
+  const { apiUrl } = useForge();
+  const socketRef = useRef<Socket | null>(null);
+  const [socket, setSocket] = useState<Socket | null>(null);
+
+  useEffect(() => {
+    if (!enabled || socketRef.current) return;
+    const token = typeof localStorage !== "undefined" ? localStorage.getItem(PUBLIC_ACCESS_TOKEN_KEY) : null;
+    const next = io(getForgeWebSocketUrl(apiUrl), { auth: { token }, transports: ["websocket"] });
+    socketRef.current = next;
+    setSocket(next);
+    // Intentionally not disconnecting on unmount — mirrors the client app, where the
+    // chat socket persists across channel selection. Callers manage room join/leave.
+  }, [enabled, apiUrl]);
+
+  return socket;
+}

package/src/data/queries/useCoachingAvailability.ts

@@ -0,0 +1,69 @@
+import type { BookingSlot } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** Bookable availability slots for a coaching product within a date range. */
+export function useCoachingAvailability(productId?: string, fromDate?: string, toDate?: string) {
+  const { client } = useForge();
+
+  return useQuery<BookingSlot[]>({
+    queryKey: ["coaching-availability", productId, { fromDate, toDate }],
+    queryFn: async () => {
+      const res = await client.get(`/public/coaching/products/${productId}/availability`, {
+        params: { fromDate, toDate },
+      });
+      return res.data;
+    },
+    enabled: !!client && !!productId && !!fromDate && !!toDate,
+  });
+}
+
+/** Reserve a coaching booking slot. Returns the created booking id. */
+export function useReserveCoachingBooking(productId?: string) {
+  const { client } = useForge();
+
+  return useMutation<{ bookingId: string }, unknown, { slotId: string }>({
+    mutationFn: async ({ slotId }) => {
+      const res = await client.post(`/public/coaching/products/${productId}/booking/reserve`, {
+        slotId,
+      });
+      return res.data;
+    },
+  });
+}
+
+export type UpdateCoachingBookingInput = {
+  bookingId: string | null;
+  email: string;
+  firstName: string;
+  lastName: string;
+  confirmIfFree?: boolean;
+  questionnaire?: unknown;
+  attributionRefId?: string;
+};
+
+/** Attach buyer details to a reserved coaching booking (confirms it if free). */
+export function useUpdateCoachingBooking(productId?: string) {
+  const { client } = useForge();
+
+  return useMutation<{ bookingId: string; isConfirmed: boolean }, unknown, UpdateCoachingBookingInput>({
+    mutationFn: async (body) => {
+      const res = await client.post(`/public/coaching/products/${productId}/booking/update`, body);
+      return res.data;
+    },
+  });
+}
+
+/** Release a reserved coaching booking slot. */
+export function useUnreserveCoachingBooking(productId?: string) {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { bookingId: string }>({
+    mutationFn: async ({ bookingId }) => {
+      const res = await client.post(`/public/coaching/products/${productId}/booking/unreserve`, {
+        bookingId,
+      });
+      return res.data;
+    },
+  });
+}