@tribe-nest/forge 1.13.0

package/src/data/queries/useCoupons.ts

@@ -0,0 +1,20 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation } from "@tanstack/react-query";
+
+export type ValidatedCoupon = {
+  code: string;
+  membershipTierId?: string;
+  membershipEndDate?: string;
+};
+
+/** Validate a coupon code (e.g. a membership coupon) for the profile. */
+export function useValidateCoupon() {
+  const { client, profileId } = useForge();
+
+  return useMutation<{ coupon: ValidatedCoupon }, unknown, { code: string; type: string }>({
+    mutationFn: async ({ code, type }) => {
+      const res = await client.post("/public/coupons/validate", { profileId, code, type });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useCourseAccess.ts

@@ -0,0 +1,50 @@
+import type { CourseAccessData } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** A purchased course-access record (course content + progress) by access id. */
+export function useCourseAccess(accessId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<CourseAccessData>({
+    queryKey: ["course-access", accessId],
+    queryFn: async () => {
+      const res = await client.get(`/public/courses/access/${accessId}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!client && !!accessId,
+  });
+}
+
+/** Save lesson video progress / completion for a course-access record. */
+export function useUpdateCourseProgress(accessId?: string) {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { lessonId: string; videoProgress: number; isCompleted?: boolean }>({
+    mutationFn: async (data) => {
+      const res = await client.post("/public/courses/progress", { accessId, ...data });
+      return res.data;
+    },
+  });
+}
+
+/**
+ * Claim course access from an emailed link — sets the member's password and
+ * returns a session token + the access id.
+ */
+export function useClaimCourseAccess() {
+  const { client } = useForge();
+
+  return useMutation<
+    { token?: string; accessId?: string },
+    unknown,
+    { token: string; password: string; firstName: string; lastName: string }
+  >({
+    mutationFn: async (body) => {
+      const res = await client.post("/public/courses/access/claim", body);
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useCourses.ts

@@ -0,0 +1,91 @@
+import type { PaginatedData, PublicCourse } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+export type CreateCourseBookingInput = {
+  email: string;
+  firstName: string;
+  lastName: string;
+  questionnaire?: unknown;
+  attributionRefId?: string;
+};
+
+/** Create a course booking (buyer details → bookingId; free courses skip payment). */
+export function useCreateCourseBooking(courseId?: string) {
+  const { client, profileId } = useForge();
+
+  return useMutation<{ bookingId: string; isFree?: boolean }, unknown, CreateCourseBookingInput>({
+    mutationFn: async (body) => {
+      const res = await client.post(`/public/courses/${courseId}/bookings`, {
+        courseId,
+        profileId,
+        ...body,
+      });
+      return res.data;
+    },
+  });
+}
+
+export interface GetCoursesParams {
+  page?: number;
+  query?: string;
+}
+
+export function useGetCourses(params?: GetCoursesParams, enabled = true) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<PublicCourse>>({
+    queryKey: ["courses", profileId, params],
+    queryFn: async () => {
+      const res = await client.get("/public/courses", {
+        params: {
+          profileId: profileId,
+          page: params?.page || 1,
+          limit: 10,
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && enabled,
+  });
+}
+
+export function useGetCourse(courseId?: string, options?: { initialData?: PublicCourse }) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PublicCourse>({
+    queryKey: ["course", profileId, { courseId }],
+    queryFn: async () => {
+      const res = await client.get(`/public/courses/${courseId}`, {
+        params: {
+          profileId: profileId,
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!courseId,
+    initialData: options?.initialData,
+  });
+}
+
+export function useGetCoursesByIds(courseIds: string[]) {
+  const { client, profileId } = useForge();
+  const idsKey = courseIds.join(",");
+
+  return useQuery<PublicCourse[]>({
+    queryKey: ["courses", "batch", profileId, idsKey],
+    queryFn: async () => {
+      const res = await client.get("/public/courses/batch", {
+        params: {
+          profileId: profileId,
+          ids: idsKey,
+        },
+      });
+      const data = res.data as PublicCourse[];
+      return courseIds
+        .map((id) => data.find((c) => c.id === id))
+        .filter((c): c is PublicCourse => c != null);
+    },
+    enabled: !!profileId && !!client && courseIds.length > 0,
+  });
+}

package/src/data/queries/useCurrencies.ts

@@ -0,0 +1,33 @@
+import { useQuery } from "@tanstack/react-query";
+import type { Currency } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+
+export interface CurrenciesResponse {
+  supportedCurrencies: Currency[];
+  userCurrency: Currency;
+  exchangeRates: Record<Currency, Record<Currency, number>>;
+}
+
+/**
+ * Supported currencies + exchange rates for the tenant (GET /public/currencies).
+ *
+ * `PublicAuthProvider` already fetches this under the same query key, so when a
+ * site renders inside the auth provider this hook just reads the shared cache.
+ * It is exported standalone so a creator rebuilding a price/currency UI can use
+ * it (and `useFormatCurrency`) without depending on the auth context.
+ */
+export function useCurrencies() {
+  const { client, profileId } = useForge();
+
+  return useQuery<CurrenciesResponse>({
+    // profileId scopes the cache — supportedCurrencies is narrowed to the tenant's
+    // connected account, so tenants must not share the same cache entry.
+    queryKey: ["public-currencies", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/currencies", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!client,
+    staleTime: 1000 * 60 * 60 * 2, // 2 hours
+  });
+}

package/src/data/queries/useDocuments.ts

@@ -0,0 +1,208 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+
+// ── Types (mirror apps/backend/src/routes/public/documents + services) ───────
+
+export type PublicDocumentKind = "proposal" | "contract";
+export type PublicDocumentStatus =
+  | "draft"
+  | "sent"
+  | "viewed"
+  | "accepted"
+  | "signed"
+  | "declined"
+  | "expired"
+  | "converted";
+
+export interface PublicDocumentPricingOption {
+  id: string;
+  label: string;
+  amountCents: number;
+  currency: string;
+  isRecurring: boolean;
+  selected: boolean;
+}
+
+export interface PublicDocumentRecipient {
+  id: string;
+  email: string;
+  name: string | null;
+  role: "signer" | "viewer";
+  status: string; // pending | viewed | signed | accepted | declined
+  requireOtp: boolean;
+  emailVerified: boolean;
+  signedName: string | null;
+  signedAt: string | null;
+}
+
+export interface PublicDocument {
+  id: string;
+  profileId: string;
+  kind: PublicDocumentKind;
+  title: string;
+  status: PublicDocumentStatus;
+  bodyType: "rich" | "pdf";
+  /** Lexical JSON (object or serialized string) when bodyType=rich. */
+  body: unknown;
+  sourcePdfUrl: string | null;
+  signedPdfUrl: string | null;
+  amountCents: number | null;
+  currency: string | null;
+  expiresAt: string | null;
+  sentAt: string | null;
+  completedAt: string | null;
+}
+
+export interface PublicDocumentResponse {
+  document: PublicDocument;
+  recipient: PublicDocumentRecipient;
+  pricingOptions: PublicDocumentPricingOption[];
+  profile: { name: string; subdomain: string } | null;
+}
+
+export interface SignDocumentResult {
+  success: boolean;
+  documentStatus?: PublicDocumentStatus;
+  allSigned?: boolean;
+  alreadySigned?: boolean;
+}
+
+export const publicDocumentQueryKey = (token: string) => ["public-document", token];
+
+/**
+ * Token-scoped public proposal/contract read (GET /public/documents/:token —
+ * the emailed magic link IS the identity, no login). Every GET records a view
+ * in the audit trail server-side, so this query is deliberately non-chatty:
+ * no window-focus refetch, no retries, infinite staleTime — refresh happens
+ * explicitly via invalidation after a sign/accept/decline mutation.
+ */
+export function usePublicDocument(token?: string) {
+  const { client } = useForge();
+
+  return useQuery<PublicDocumentResponse>({
+    queryKey: publicDocumentQueryKey(token ?? ""),
+    queryFn: async () => {
+      const res = await client.get(`/public/documents/${token}`);
+      return res.data as PublicDocumentResponse;
+    },
+    enabled: !!token && !!client,
+    retry: false,
+    staleTime: Infinity,
+    refetchOnWindowFocus: false,
+  });
+}
+
+/** Email the recipient a one-time code — POST /public/documents/:token/verify-email. */
+export function useRequestDocumentOtp(token: string) {
+  const { client } = useForge();
+  return useMutation({
+    mutationFn: async () => {
+      const res = await client.post(`/public/documents/${token}/verify-email`, {});
+      return res.data as { success: boolean };
+    },
+  });
+}
+
+/** Confirm the emailed 6-digit code — POST /public/documents/:token/confirm-otp. */
+export function useConfirmDocumentOtp(token: string) {
+  const { client } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (code: string) => {
+      const res = await client.post(`/public/documents/${token}/confirm-otp`, { code });
+      return res.data as { success: boolean };
+    },
+    onSuccess: () => {
+      // Flip recipient.emailVerified locally instead of re-fetching (a re-fetch
+      // would write another `viewed` audit event).
+      queryClient.setQueryData<PublicDocumentResponse>(publicDocumentQueryKey(token), (prev) =>
+        prev ? { ...prev, recipient: { ...prev.recipient, emailVerified: true } } : prev,
+      );
+    },
+  });
+}
+
+/** Sign a contract (optional drawn PNG) — POST /public/documents/:token/sign.
+ * The signed legal name is derived server-side from the invited recipient
+ * (admin-entered, read-only to the signer), so it is never sent from here. */
+export function useSignDocument(token: string) {
+  const { client } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: { signatureImage?: string } = {}) => {
+      const res = await client.post(`/public/documents/${token}/sign`, {
+        ...(input.signatureImage ? { signatureImage: input.signatureImage } : {}),
+        consent: true,
+      });
+      return res.data as SignDocumentResult;
+    },
+    onSuccess: () => {
+      // Re-fetch to pick up signedPdfUrl + final statuses for the confirmation view.
+      queryClient.invalidateQueries({ queryKey: publicDocumentQueryKey(token) });
+    },
+  });
+}
+
+/** Accept a proposal (optionally picking a pricing option) — POST /public/documents/:token/accept. */
+export function useAcceptDocument(token: string) {
+  const { client } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: { pricingOptionId?: string }) => {
+      const res = await client.post(`/public/documents/${token}/accept`, input);
+      return res.data as SignDocumentResult;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: publicDocumentQueryKey(token) });
+    },
+  });
+}
+
+/** Decline a proposal/contract with an optional reason — POST /public/documents/:token/decline. */
+export function useDeclineDocument(token: string) {
+  const { client } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: { reason?: string }) => {
+      const res = await client.post(`/public/documents/${token}/decline`, {
+        ...(input.reason ? { reason: input.reason } : {}),
+      });
+      return res.data as SignDocumentResult;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: publicDocumentQueryKey(token) });
+    },
+  });
+}
+
+/** Downloads the signed PDF (blob) and triggers a browser save. */
+export function useDownloadSignedDocument(token: string, title?: string) {
+  const { client } = useForge();
+  return useMutation({
+    mutationFn: async () => {
+      const res = await client.get(`/public/documents/${token}/download`, {
+        responseType: "blob",
+      });
+      return res.data as Blob;
+    },
+    onSuccess: (blob) => {
+      const filename = `${(title || "document")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60)}-signed.pdf`;
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = filename;
+      a.click();
+      URL.revokeObjectURL(url);
+    },
+  });
+}
+
+/** Best-effort message extraction from an Axios error. */
+export function getDocumentApiErrorMessage(error: unknown, fallback: string): string {
+  const message = (error as { response?: { data?: { message?: string } } })?.response?.data?.message;
+  return message || fallback;
+}

package/src/data/queries/useDonations.ts

@@ -0,0 +1,29 @@
+import type { PublicDonation } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** A single donation configuration by id. */
+export function useGetDonation(donationId?: string | null, enabled = true) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PublicDonation>({
+    queryKey: ["donation", donationId],
+    queryFn: async () => {
+      const res = await client.get(`/public/donations/${donationId}`);
+      return res.data;
+    },
+    enabled: !!client && !!donationId && !!profileId && enabled,
+  });
+}
+
+/** Track a donation-button view/click (fire-and-forget). */
+export function useTrackDonationView() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { donationId: string }>({
+    mutationFn: async ({ donationId }) => {
+      const res = await client.post(`/public/donations/${donationId}/track`);
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useEngagement.ts

@@ -0,0 +1,115 @@
+import type { IPublicComment, EngagementEntityType } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+// Likes / saves / comments are entity-scoped engagement endpoints (a post today,
+// other entity types later), so the hooks take { entityId, entityType }.
+
+/** Whether the current member has liked an entity. */
+export function useLikeStatus(entityId?: string, entityType: EngagementEntityType = "post", enabled = true) {
+  const { client } = useForge();
+
+  return useQuery<boolean>({
+    queryKey: ["like-status", entityType, entityId],
+    queryFn: async () => {
+      const res = await client.get("/public/likes/status", {
+        params: { entityId, entityType },
+      });
+      return res.data.liked;
+    },
+    enabled: !!client && !!entityId && enabled,
+  });
+}
+
+/** Whether the current member has saved an entity. */
+export function useSaveStatus(entityId?: string, entityType: EngagementEntityType = "post", enabled = true) {
+  const { client } = useForge();
+
+  return useQuery<boolean>({
+    queryKey: ["save-status", entityType, entityId],
+    queryFn: async () => {
+      const res = await client.get("/public/saves/status", {
+        params: { entityId, entityType },
+      });
+      return res.data.saved;
+    },
+    enabled: !!client && !!entityId && enabled,
+  });
+}
+
+/** Like + comment counts for an entity. */
+export function useEngagementCounts(entityId?: string, entityType: EngagementEntityType = "post", enabled = true) {
+  const { client } = useForge();
+
+  return useQuery<{ likeCount: number; commentCount: number }>({
+    queryKey: ["engagement-counts", entityType, entityId],
+    queryFn: async () => {
+      const [likeRes, commentRes] = await Promise.all([
+        client.get("/public/likes/count", { params: { entityId, entityType } }),
+        client.get("/public/comments/count", { params: { entityId, entityType } }),
+      ]);
+      return { likeCount: likeRes.data.count, commentCount: commentRes.data.count };
+    },
+    enabled: !!client && !!entityId && enabled,
+  });
+}
+
+/** Comments on an entity. */
+export function useComments(entityId?: string, entityType: EngagementEntityType = "post", enabled = true) {
+  const { client } = useForge();
+
+  return useQuery<IPublicComment[]>({
+    queryKey: ["comments", entityType, entityId],
+    queryFn: async () => {
+      const res = await client.get("/public/comments", {
+        params: { entityId, entityType },
+      });
+      return res.data.comments;
+    },
+    enabled: !!client && !!entityId && enabled,
+  });
+}
+
+/** Like (`liked: true`) or unlike (`liked: false`) an entity. */
+export function useToggleLike() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { entityId: string; entityType?: EngagementEntityType; liked: boolean }>({
+    mutationFn: async ({ entityId, entityType = "post", liked }) => {
+      if (liked) {
+        const res = await client.post("/public/likes", { entityId, entityType });
+        return res.data;
+      }
+      const res = await client.delete("/public/likes", { data: { entityId, entityType } });
+      return res.data;
+    },
+  });
+}
+
+/** Save (`saved: true`) or unsave (`saved: false`) an entity. */
+export function useToggleSave() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { entityId: string; entityType?: EngagementEntityType; saved: boolean }>({
+    mutationFn: async ({ entityId, entityType = "post", saved }) => {
+      if (saved) {
+        const res = await client.post("/public/saves", { entityId, entityType });
+        return res.data;
+      }
+      const res = await client.delete("/public/saves", { data: { entityId, entityType } });
+      return res.data;
+    },
+  });
+}
+
+/** Add a comment to an entity. */
+export function useAddComment() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { entityId: string; entityType?: EngagementEntityType; content: string }>({
+    mutationFn: async ({ entityId, entityType = "post", content }) => {
+      const res = await client.post("/public/comments", { entityId, entityType, content });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useEvents.ts

@@ -0,0 +1,69 @@
+import type { IEvent } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** All published events for the profile. */
+export function useEvents() {
+  const { client, profileId } = useForge();
+
+  return useQuery<IEvent[]>({
+    queryKey: ["events", profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/events`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/**
+ * A single event by id or slug.
+ *
+ * Pass `initialData` (e.g. an event fetched server-side in a route loader) to
+ * seed the query — the hook then returns data on first render with no loading
+ * state, so the page can be server-rendered for SEO with no client spinner.
+ */
+export function useEvent(id?: string, options?: { initialData?: IEvent }) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IEvent>({
+    queryKey: ["event", id, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/events/${id}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!id && !!profileId && !!client,
+    initialData: options?.initialData,
+  });
+}
+
+export type CreateEventOrderInput = {
+  items: Record<string, number>;
+  email: string;
+  firstName?: string;
+  lastName?: string;
+  questionnaire?: unknown;
+  attributionRefId?: string;
+};
+
+export type CreateEventOrderResult = {
+  orderId: string;
+  isFreeCheckout?: boolean;
+  totalAmount?: number;
+};
+
+/** Create an event ticket order (the step before start-payment). */
+export function useCreateEventOrder(eventId?: string) {
+  const { client, profileId } = useForge();
+
+  return useMutation<CreateEventOrderResult, unknown, CreateEventOrderInput>({
+    mutationFn: async (body) => {
+      const res = await client.post(`/public/events/${eventId}/orders`, { ...body, profileId });
+      return res.data;
+    },
+  });
+}