@tribe-nest/forge 1.13.0

package/src/data/queries/useFinalize.ts

@@ -0,0 +1,109 @@
+import { OrderStatus, type IPublicOrder, type ITicketOrder, type CoachingBooking, type CourseBooking } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+// The payment "finalize" endpoints reconcile provider state on the return page.
+// They're POSTs but idempotent, so they're modeled as load-time queries.
+
+// Order is still settling (the payment provider's webhook hasn't marked it paid
+// yet) — safe to poll a return page until it resolves.
+const PENDING_ORDER_STATES = new Set<OrderStatus>([OrderStatus.InitiatedPayment, OrderStatus.Processing]);
+
+/**
+ * Finalize a cart/product order (`/public/orders/finalize`). The backend only
+ * needs `orderId` — it reads the stored payment ref off the order to reconcile
+ * with the gateway — so nothing else is sent.
+ */
+export function useOrderFinalize(
+  args: { orderId?: string },
+  opts?: {
+    /**
+     * Poll while the order is still `initiated_payment` / `processing` (the
+     * gateway webhook race on the return page), stopping the moment it settles
+     * to paid/failed. The confirmation UI passes this so a just-paid order
+     * doesn't get stuck showing "processing".
+     */
+    pollWhilePending?: boolean;
+  },
+) {
+  const { client, profileId } = useForge();
+  const { orderId } = args;
+
+  return useQuery<IPublicOrder>({
+    queryKey: ["paymentStatus", profileId, orderId],
+    queryFn: async () => {
+      const res = await client.post("/public/orders/finalize", { profileId, orderId });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!orderId,
+    refetchInterval: opts?.pollWhilePending
+      ? (query) => (query.state.data && PENDING_ORDER_STATES.has(query.state.data.status) ? 2500 : false)
+      : false,
+  });
+}
+
+/** Finalize an event ticket order (`/public/events/:eventId/finalize`). */
+export function useEventOrderFinalize(eventId?: string, orderId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<ITicketOrder>({
+    queryKey: ["eventTicketOrderStatus", profileId, orderId],
+    queryFn: async () => {
+      const res = await client.post(`/public/events/${eventId}/finalize`, {
+        profileId,
+        orderId,
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** Finalize a coaching booking (`/public/coaching/products/:productId/finalize`). */
+export function useCoachingBookingFinalize(productId?: string, orderId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<CoachingBooking>({
+    queryKey: ["coachingBookingStatus", profileId, orderId],
+    queryFn: async () => {
+      const res = await client.post(`/public/coaching/products/${productId}/finalize`, {
+        profileId,
+        orderId,
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!orderId,
+  });
+}
+
+/** Finalize a donation after in-place confirmation (`/public/donations/finalize`). */
+export function useDonationFinalize() {
+  const { client, profileId } = useForge();
+
+  return useMutation<{ status: "succeeded" | "failed" | "pending" }, unknown, { donationPaymentId: string }>({
+    mutationFn: async ({ donationPaymentId }) => {
+      const res = await client.post("/public/donations/finalize", {
+        donationPaymentId,
+        profileId,
+      });
+      return res.data;
+    },
+  });
+}
+
+/** Finalize a course booking (`/public/courses/:courseId/finalize`). */
+export function useCourseBookingFinalize(courseId?: string, bookingId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<CourseBooking>({
+    queryKey: ["courseBookingStatus", profileId, bookingId],
+    queryFn: async () => {
+      const res = await client.post(`/public/courses/${courseId}/finalize`, {
+        profileId,
+        bookingId,
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!bookingId,
+  });
+}

package/src/data/queries/useForms.ts

@@ -0,0 +1,31 @@
+import type { FormData, FormAnswerEntry } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** A single public form (fields + conditional edges) by id. */
+export function usePublicForm(formId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<FormData>({
+    queryKey: ["publicForm", formId],
+    queryFn: async () => {
+      const res = await client.get(`/public/forms/${formId}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!client && !!formId,
+  });
+}
+
+/** Submit answers to a public form. */
+export function useSubmitPublicForm(formId?: string) {
+  const { client } = useForge();
+
+  return useMutation({
+    mutationFn: async (answers: FormAnswerEntry[]) => {
+      const res = await client.post(`/public/forms/${formId}/submit`, { answers });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useInvoice.ts

@@ -0,0 +1,65 @@
+import type { InvoiceData } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** A single public invoice by id. */
+export function useInvoice(invoiceId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<InvoiceData>({
+    queryKey: ["invoice", invoiceId, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/invoices/${invoiceId}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!invoiceId,
+  });
+}
+
+/** Download an invoice as a PDF (returns the blob to save). */
+export function useDownloadInvoicePdf(invoiceId?: string) {
+  const { client, profileId } = useForge();
+
+  return useMutation<Blob, unknown, void>({
+    mutationFn: async () => {
+      const res = await client.get(`/public/invoices/${invoiceId}/pdf`, {
+        params: { profileId },
+        responseType: "blob",
+      });
+      return res.data;
+    },
+  });
+}
+
+export type InvoiceFinalizeResult = {
+  id: string;
+  invoiceNumber: string;
+  clientName: string;
+  clientEmail: string;
+  total: string;
+  currency: string;
+  status: string;
+  paidAt: string | null;
+  profileName: string;
+};
+
+/**
+ * Finalize an invoice payment on the return/confirmation page. The POST is
+ * idempotent (reconciles provider state) so it's modeled as a load-time query.
+ */
+export function useInvoiceFinalize(invoiceId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<InvoiceFinalizeResult>({
+    queryKey: ["invoice-finalize", invoiceId, profileId],
+    queryFn: async () => {
+      const res = await client.post(`/public/invoices/${invoiceId}/finalize`, {
+        profileId,
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!invoiceId,
+  });
+}

package/src/data/queries/useLeadMagnet.ts

@@ -0,0 +1,96 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+export type LeadMagnetMedia = {
+  url: string;
+  filename?: string;
+  type?: string;
+};
+
+export type LeadMagnetConfirmation = {
+  leadMagnet: {
+    id: string;
+    thankYouMessage?: string | null;
+    media?: LeadMagnetMedia[];
+  };
+  profile: {
+    id: string;
+    name: string;
+  };
+};
+
+/**
+ * Confirms a lead-magnet subscription link and returns the lead magnet + profile.
+ * The double opt-in confirm is a read (idempotent GET) — the download tracking
+ * POST stays a separate flow.
+ */
+export function useLeadMagnetConfirm(leadMagnetId?: string, subscriberId?: string) {
+  const { client } = useForge();
+
+  return useQuery<LeadMagnetConfirmation>({
+    queryKey: ["lead-magnet-confirm", leadMagnetId, subscriberId],
+    queryFn: async () => {
+      const res = await client.get(`/public/email-lists/lead-magnet/confirm`, {
+        params: { leadMagnetId, subscriberId },
+      });
+      return res.data;
+    },
+    enabled: !!client && !!leadMagnetId && !!subscriberId,
+    retry: false,
+  });
+}
+
+/** Confirm a double-opt-in email subscription link. Returns the profile. */
+export function useConfirmEmailSubscription(subscriberId?: string, enabled = true) {
+  const { client } = useForge();
+
+  return useQuery<{ profile: { id: string; name: string } }>({
+    queryKey: ["confirm-email-subscription", subscriberId],
+    queryFn: async () => {
+      const res = await client.get(`/public/email-lists/confirm-subscription`, {
+        params: { subscriberId },
+      });
+      return res.data;
+    },
+    enabled: !!client && !!subscriberId && enabled,
+    retry: false,
+  });
+}
+
+export type JoinEmailListInput = {
+  email: string;
+  emailListId?: string;
+  leadMagnetId?: string;
+  firstName?: string;
+  /** @deprecated send `firstName` — kept only for backward compatibility. */
+  name?: string;
+  phoneNumber?: string;
+};
+
+/** Join an email list / subscribe (may require double opt-in confirmation). */
+export function useJoinEmailList() {
+  const { client, profileId } = useForge();
+
+  return useMutation<{ requiresConfirmation?: boolean }, unknown, JoinEmailListInput>({
+    mutationFn: async (body) => {
+      const res = await client.post(`/public/email-lists/join`, { ...body, profileId });
+      return res.data;
+    },
+  });
+}
+
+/** Track a lead-magnet download (fire-and-forget; the file download proceeds regardless). */
+export function useTrackLeadMagnetDownload() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { leadMagnetId?: string; subscriberId?: string }>({
+    mutationFn: async ({ leadMagnetId, subscriberId }) => {
+      const res = await client.post(`/public/email-lists/lead-magnet/download`, {
+        leadMagnetId,
+        subscriberId,
+        data: { userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined },
+      });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useMembership.ts

@@ -0,0 +1,20 @@
+import type { MembershipTier } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+export function useGetMembershipTiers() {
+  const { client, profileId } = useForge();
+
+  return useQuery<MembershipTier[]>({
+    queryKey: ["membership-tiers", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/membership-tiers", {
+        params: {
+          profileId: profileId,
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}

package/src/data/queries/useNotifications.ts

@@ -0,0 +1,267 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useState } from "react";
+
+/**
+ * Member notification headless hooks — the FROZEN public contract that the
+ * apps/client PWA and every generated custom-code site consume. Speaks ONLY the
+ * `/public/notifications/*` API (see docs/membership-notifications-initiative.md
+ * "API surface"). Moved here from apps/client so custom-code sites get push
+ * subscription registration, inbox, and a settings matrix with no apps/client
+ * code.
+ *
+ * === FROZEN PUSH-SUBSCRIPTION CONTRACT (do not break; PWA lane depends on it) ===
+ *  usePushSubscription(profileId) → {
+ *    isSupported, permissionState, isSubscribed, isLoading,
+ *    subscribe(): Promise<boolean>,   // requests permission, subscribes, POSTs to backend
+ *    unsubscribe(): Promise<boolean>, // unsubscribes locally + POSTs /unsubscribe
+ *  }
+ *  Backend endpoints used:
+ *    GET  /public/notifications/vapid-key        → { vapidPublicKey }
+ *    POST /public/notifications/subscribe        { profileId, endpoint, p256dh, auth, userAgent? }
+ *    POST /public/notifications/unsubscribe      { profileId, endpoint }
+ *  SW push payload shape (what the generated service worker must render):
+ *    { type, title, body, url, profileId, channelId?, spaceId?, entityId? }
+ * ================================================================================
+ */
+
+// ---- shared types --------------------------------------------------------
+
+export type NotificationChannel = "inapp" | "push" | "email";
+
+export type NotificationType =
+  | "dm"
+  | "chat_message"
+  | "mention"
+  | "reply"
+  | "reaction"
+  | "new_community_post"
+  | "new_post"
+  | "event_reminder"
+  | "stream_live"
+  | "mod";
+
+export interface NotificationInboxItem {
+  id: string;
+  profileId: string;
+  accountId: string;
+  type: NotificationType | string;
+  entityType: string | null;
+  entityId: string | null;
+  readAt: string | null;
+  createdAt: string;
+  data: {
+    title?: string;
+    body?: string;
+    url?: string;
+    actorName?: string;
+    actorAccountId?: string;
+  } | null;
+}
+
+export type DigestCadence = "off" | "inapp_only" | "hourly" | "daily";
+
+export interface NotificationMatrix {
+  id: string;
+  accountId: string;
+  profileId: string;
+  digestCadence: DigestCadence;
+  // fully-resolved matrix ("<type>.<channel>" -> boolean), defaults merged over overrides
+  preferences: Record<string, boolean>;
+  // raw explicit overrides only
+  overrides: Record<string, boolean>;
+  defaults: Record<string, { inapp: boolean; push: boolean; email: boolean; emailMode: string }>;
+}
+
+// ---- query keys ----------------------------------------------------------
+
+const keys = {
+  inbox: (profileId?: string, unreadOnly?: boolean) =>
+    ["public-notifications-inbox", profileId, unreadOnly] as const,
+  prefs: (profileId?: string) => ["public-notification-preferences", profileId] as const,
+};
+
+// ---- helpers -------------------------------------------------------------
+
+function urlBase64ToUint8Array(base64String: string) {
+  const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const rawData = window.atob(base64);
+  const outputArray = new Uint8Array(rawData.length);
+  for (let i = 0; i < rawData.length; ++i) outputArray[i] = rawData.charCodeAt(i);
+  return outputArray;
+}
+
+// ---- usePushSubscription -------------------------------------------------
+
+/**
+ * Web-push subscription registration (headless). Handles permission,
+ * pushManager.subscribe with the platform VAPID key, and POST to the backend.
+ * Migrated verbatim from apps/client/src/lib/hooks/usePushNotifications so the
+ * behaviour (and the API contract above) is identical for custom-code sites.
+ */
+export function usePushSubscription(profileId: string) {
+  const { client } = useForge();
+  const [permissionState, setPermissionState] = useState<NotificationPermission>("default");
+  const [isSubscribed, setIsSubscribed] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isSupported, setIsSupported] = useState(false);
+
+  useEffect(() => {
+    const supported = "Notification" in window && "serviceWorker" in navigator && "PushManager" in window;
+    setIsSupported(supported);
+    if (!supported) {
+      setIsLoading(false);
+      return;
+    }
+    setPermissionState(Notification.permission);
+    navigator.serviceWorker.ready.then((registration) => {
+      registration.pushManager.getSubscription().then((subscription) => {
+        setIsSubscribed(!!subscription);
+        setIsLoading(false);
+      });
+    });
+  }, []);
+
+  const subscribe = useCallback(async () => {
+    if (!isSupported || !client) return false;
+    try {
+      setIsLoading(true);
+      const permission = await Notification.requestPermission();
+      setPermissionState(permission);
+      if (permission !== "granted") {
+        setIsLoading(false);
+        return false;
+      }
+      const { data } = await client.get("/public/notifications/vapid-key");
+      if (!data?.vapidPublicKey) {
+        setIsLoading(false);
+        return false;
+      }
+      const registration = await navigator.serviceWorker.ready;
+      const subscription = await registration.pushManager.subscribe({
+        userVisibleOnly: true,
+        applicationServerKey: urlBase64ToUint8Array(data.vapidPublicKey),
+      });
+      const json = subscription.toJSON();
+      await client.post("/public/notifications/subscribe", {
+        profileId,
+        endpoint: json.endpoint,
+        p256dh: json.keys?.p256dh,
+        auth: json.keys?.auth,
+        userAgent: navigator.userAgent,
+      });
+      setIsSubscribed(true);
+      setIsLoading(false);
+      return true;
+    } catch (error) {
+      console.error("Push subscription error:", error);
+      setIsLoading(false);
+      return false;
+    }
+  }, [isSupported, client, profileId]);
+
+  const unsubscribe = useCallback(async () => {
+    if (!isSupported || !client) return false;
+    try {
+      setIsLoading(true);
+      const registration = await navigator.serviceWorker.ready;
+      const subscription = await registration.pushManager.getSubscription();
+      if (subscription) {
+        const endpoint = subscription.endpoint;
+        await subscription.unsubscribe();
+        await client.post("/public/notifications/unsubscribe", { profileId, endpoint });
+      }
+      setIsSubscribed(false);
+      setIsLoading(false);
+      return true;
+    } catch (error) {
+      console.error("Push unsubscribe error:", error);
+      setIsLoading(false);
+      return false;
+    }
+  }, [isSupported, client, profileId]);
+
+  return { permissionState, isSubscribed, isLoading, subscribe, unsubscribe, isSupported };
+}
+
+// ---- useNotificationInbox ------------------------------------------------
+
+/** In-app inbox (GET /public/notifications/inbox). Returns { data, unreadCount }. */
+export function useNotificationInbox({ unreadOnly = false, page = 1, limit = 50 } = {}) {
+  const { client, profileId } = useForge();
+  return useQuery<{ data: NotificationInboxItem[]; unreadCount: number }>({
+    queryKey: keys.inbox(profileId, unreadOnly),
+    queryFn: async () => {
+      const res = await client.get("/public/notifications/inbox", {
+        params: { profileId, page, limit, unreadOnly },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** Unread count for the bell, polled every 30s. */
+export function useNotificationUnreadCount(enabled = true) {
+  const { client, profileId } = useForge();
+  return useQuery<number>({
+    queryKey: [...keys.inbox(profileId, true), "count"],
+    queryFn: async () => {
+      const res = await client.get("/public/notifications/inbox", {
+        params: { profileId, page: 1, limit: 1, unreadOnly: true },
+      });
+      return res.data.unreadCount as number;
+    },
+    enabled: enabled && !!profileId && !!client,
+    refetchInterval: 30000,
+  });
+}
+
+/** Mark notifications read — omit ids to mark ALL unread as read. */
+export function useMarkNotificationsRead() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (ids?: string[]) => {
+      await client.post("/public/notifications/mark-read", { profileId, ids });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["public-notifications-inbox"] });
+    },
+  });
+}
+
+// ---- useNotificationPreferences ------------------------------------------
+
+/** The member's notification matrix + digest cadence (GET /preferences). */
+export function useNotificationMatrix(enabled = true) {
+  const { client, profileId } = useForge();
+  return useQuery<NotificationMatrix>({
+    queryKey: keys.prefs(profileId),
+    queryFn: async () => {
+      const res = await client.get("/public/notifications/preferences", { params: { profileId } });
+      return res.data;
+    },
+    enabled: enabled && !!profileId && !!client,
+  });
+}
+
+/** Update the matrix and/or digest cadence (PUT /preferences). */
+export function useUpdateNotificationMatrix() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation<
+    NotificationMatrix,
+    unknown,
+    { preferences?: Record<string, boolean>; digestCadence?: DigestCadence }
+  >({
+    mutationFn: async (body) => {
+      const res = await client.put("/public/notifications/preferences", { profileId, ...body });
+      return res.data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: keys.prefs(profileId) });
+    },
+  });
+}

package/src/data/queries/useOffers.ts

@@ -0,0 +1,56 @@
+import type { PublicOffer } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** A single offer by id. */
+export function useGetOffer(offerId?: string | null, enabled = true) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PublicOffer>({
+    queryKey: ["offer", offerId],
+    queryFn: async () => {
+      const res = await client.get(`/public/offers/${offerId}`);
+      return res.data;
+    },
+    enabled: !!client && !!offerId && !!profileId && enabled,
+  });
+}
+
+/**
+ * The underlying item an offer points to (product / event / course / coaching).
+ * Returns `any` because the shape is polymorphic by `offerType` — the caller
+ * renders the type-specific component.
+ */
+export function useOfferItem(offer?: PublicOffer | null, enabled = true) {
+  const { client, profileId } = useForge();
+
+  return useQuery({
+    queryKey: ["offer-item", offer?.id, offer?.offerType, offer?.itemId],
+    queryFn: async () => {
+      if (!offer) return null;
+      const paths: Record<string, string> = {
+        product: `/public/products/${offer.itemId}`,
+        event: `/public/events/${offer.itemId}`,
+        course: `/public/courses/${offer.itemId}`,
+        coaching: `/public/coaching/products/${offer.itemId}`,
+      };
+      const path = paths[offer.offerType];
+      if (!path) return null;
+      const res = await client.get(path, { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!client && !!offer && !!profileId && enabled,
+  });
+}
+
+/** Track an offer-button click (fire-and-forget). */
+export function useTrackOfferClick() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { offerId: string }>({
+    mutationFn: async ({ offerId }) => {
+      const res = await client.post(`/public/offers/${offerId}/track`);
+      return res.data;
+    },
+  });
+}