@tribe-nest/forge 1.13.0

package/src/data/queries/useOrders.ts

@@ -0,0 +1,71 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation } from "@tanstack/react-query";
+
+/**
+ * The minimal cart-item shape the order endpoint needs. The full cart `CartItem`
+ * is a superset and assignable; lighter callers (e.g. a single-product offer)
+ * supply just these fields.
+ */
+export type OrderCartItem = {
+  productId: string;
+  productVariantId: string;
+  title: string;
+  price: number;
+  quantity: number;
+  coverImage?: string;
+  isGift?: boolean;
+  recipientName?: string;
+  recipientEmail?: string;
+  recipientMessage?: string;
+};
+
+export type CreateOrderShippingRate = {
+  groupId: string;
+  type: "flat" | "dynamic" | "external";
+  productIds: string[];
+  rateId: string;
+  shipmentId: string;
+  amount: number;
+  currency?: string;
+  carrier: string;
+  service: string;
+};
+
+export type CreateOrderInput = {
+  amount: number;
+  email: string;
+  firstName?: string;
+  lastName?: string;
+  accountId?: string;
+  cartItems: OrderCartItem[];
+  shippingAddress?: {
+    address1: string;
+    city: string;
+    stateCode: string;
+    countryCode: string;
+    zip: string;
+  };
+  couponCode?: string;
+  selectedShippingRates?: CreateOrderShippingRate[];
+  joinEmailList?: boolean;
+  attributionRefId?: string;
+};
+
+export type CreateOrderResult = {
+  orderId: string;
+  totalAmount: number;
+  subTotal: number;
+  shippingCosts?: { deliveryGroupId: string; amount: number; currency: string }[];
+};
+
+/** Create a cart/product order (the step before start-payment). */
+export function useCreateOrder() {
+  const { client, profileId } = useForge();
+
+  return useMutation<CreateOrderResult, unknown, CreateOrderInput>({
+    mutationFn: async (input) => {
+      const res = await client.post("/public/orders", { ...input, profileId });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/usePWA.ts

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useState } from "react";
+
+/**
+ * Headless PWA install-prompt hook — the versioned Forge primitive that powers
+ * `<InstallBanner/>` (forge/ui) and any custom install UI on a code site. Ported
+ * from apps/client/src/lib/hooks/usePWA.ts, plus iOS + standalone detection
+ * (Safari never fires `beforeinstallprompt`, so iOS needs the manual
+ * "Share → Add to Home Screen" path).
+ *
+ *   const { isInstallable, isInstalled, isIOS, isStandalone, promptInstall } = useInstallPrompt();
+ *
+ * SSR-safe: everything runs inside effects, so the initial server render is a
+ * stable "nothing installable/installed" state.
+ */
+interface BeforeInstallPromptEvent extends Event {
+  prompt(): Promise<void>;
+  userChoice: Promise<{ outcome: "accepted" | "dismissed" }>;
+}
+
+export interface InstallPromptState {
+  /** A `beforeinstallprompt` event was captured (Android/desktop Chromium). */
+  isInstallable: boolean;
+  /** The app is running installed (standalone display-mode or iOS standalone). */
+  isInstalled: boolean;
+  /** iOS Safari — no `beforeinstallprompt`; show the Add-to-Home-Screen guide. */
+  isIOS: boolean;
+  /** Currently rendered in standalone (installed) display mode. */
+  isStandalone: boolean;
+  /** Fire the native install prompt; resolves true if the user accepted. */
+  promptInstall: () => Promise<boolean>;
+}
+
+function detectIOS(): boolean {
+  if (typeof navigator === "undefined") return false;
+  const ua = navigator.userAgent || "";
+  const iOSDevice = /iPad|iPhone|iPod/.test(ua);
+  // iPadOS 13+ reports as Mac; detect via touch points.
+  const iPadOS = navigator.platform === "MacIntel" && (navigator as { maxTouchPoints?: number }).maxTouchPoints! > 1;
+  return iOSDevice || iPadOS;
+}
+
+function detectStandalone(): boolean {
+  if (typeof window === "undefined") return false;
+  const mm = window.matchMedia && window.matchMedia("(display-mode: standalone)").matches;
+  // iOS Safari exposes navigator.standalone instead of the media query.
+  const iosStandalone = (window.navigator as { standalone?: boolean }).standalone === true;
+  return !!mm || iosStandalone;
+}
+
+export function useInstallPrompt(): InstallPromptState {
+  const [deferredPrompt, setDeferredPrompt] = useState<BeforeInstallPromptEvent | null>(null);
+  const [isInstallable, setIsInstallable] = useState(false);
+  const [isInstalled, setIsInstalled] = useState(false);
+  const [isIOS, setIsIOS] = useState(false);
+  const [isStandalone, setIsStandalone] = useState(false);
+
+  useEffect(() => {
+    const ios = detectIOS();
+    const standalone = detectStandalone();
+    setIsIOS(ios);
+    setIsStandalone(standalone);
+    if (standalone) setIsInstalled(true);
+
+    const handleBeforeInstallPrompt = (e: Event) => {
+      e.preventDefault();
+      setDeferredPrompt(e as BeforeInstallPromptEvent);
+      setIsInstallable(true);
+    };
+    const handleAppInstalled = () => {
+      setIsInstalled(true);
+      setIsInstallable(false);
+      setDeferredPrompt(null);
+    };
+
+    window.addEventListener("beforeinstallprompt", handleBeforeInstallPrompt);
+    window.addEventListener("appinstalled", handleAppInstalled);
+    return () => {
+      window.removeEventListener("beforeinstallprompt", handleBeforeInstallPrompt);
+      window.removeEventListener("appinstalled", handleAppInstalled);
+    };
+  }, []);
+
+  const promptInstall = useCallback(async () => {
+    if (!deferredPrompt) return false;
+    try {
+      await deferredPrompt.prompt();
+      const { outcome } = await deferredPrompt.userChoice;
+      if (outcome === "accepted") {
+        setIsInstalled(true);
+        setIsInstallable(false);
+        setDeferredPrompt(null);
+        return true;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }, [deferredPrompt]);
+
+  return { isInstallable, isInstalled, isIOS, isStandalone, promptInstall };
+}

package/src/data/queries/usePageActions.ts

@@ -0,0 +1,36 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+export type PageActionType =
+  | "newsletter"
+  | "lead_magnet"
+  | "offer"
+  | "product_cards"
+  | "donation"
+  | "membership"
+  | "button";
+
+export interface PageActionDescriptor {
+  id: string;
+  type: PageActionType;
+  config: Record<string, unknown>;
+}
+
+/**
+ * Resolves the page-action descriptors for a page slot (server applies the
+ * per-entity-override-vs-default logic). The shared <PageActions> renderer maps
+ * each descriptor to its Forge primitive.
+ */
+export function usePageActions(pageType: string, entityId?: string, placement = "after_content") {
+  const { client, profileId } = useForge();
+  return useQuery<{ actions: PageActionDescriptor[] }>({
+    queryKey: ["page-actions", profileId, pageType, placement, entityId],
+    queryFn: async () => {
+      const res = await client.get("/public/page-actions", {
+        params: { profileId, pageType, placement, entityId },
+      });
+      return res.data;
+    },
+    enabled: !!client && !!profileId && !!pageType,
+  });
+}

package/src/data/queries/usePaymentFlow.ts

@@ -0,0 +1,80 @@
+import { useEffect, useRef } from "react";
+import type { PaymentFlowResult, PaymentStartResponse } from "../../types/models";
+import { PaymentProviderName } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation } from "@tanstack/react-query";
+
+export interface UsePaymentFlowOptions {
+  /** The `start-payment` endpoint for this domain (resource already created). */
+  path?: string;
+  /** Domain-specific body (orderId / bookingId / donation fields, etc.). */
+  body?: Record<string, unknown>;
+  /** Where the provider should return the buyer after payment. */
+  returnUrl?: string;
+  /** Fire automatically once path/returnUrl/profile are ready (default true). */
+  autoStart?: boolean;
+  /** Gate auto-start on extra readiness (default true). */
+  enabled?: boolean;
+  /** Redirect to the Paystack checkout URL on success (default true). */
+  paystackRedirect?: boolean;
+}
+
+/**
+ * Starts a payment against any `/public/<domain>/.../start-payment` endpoint and
+ * normalizes the result: resolves the provider (the field is named differently
+ * per domain) and, for Paystack, redirects to the hosted checkout. The Stripe
+ * UI (Elements + confirm) stays in the app — this hook only owns the data.
+ */
+export function usePaymentFlow(opts: UsePaymentFlowOptions) {
+  const { client, profileId } = useForge();
+  const { path, body, returnUrl, autoStart = true, enabled = true, paystackRedirect = true } = opts;
+  const startedRef = useRef(false);
+
+  const mutation = useMutation<PaymentFlowResult, unknown, Record<string, unknown> | undefined>({
+    mutationFn: async (override) => {
+      // override wins — click-driven flows pass a just-created orderId/returnUrl.
+      const res = await client.post(path as string, { ...body, profileId, returnUrl, ...(override ?? {}) });
+      const data = res.data as PaymentStartResponse;
+      const provider = (data.paymentProvider ?? data.paymentProviderName) as PaymentProviderName | undefined;
+
+      if (
+        paystackRedirect &&
+        provider === PaymentProviderName.Paystack &&
+        data.paymentSecret &&
+        typeof window !== "undefined"
+      ) {
+        window.location.href = data.paymentSecret;
+      }
+
+      return { ...data, provider };
+    },
+  });
+
+  const { mutate, mutateAsync } = mutation;
+
+  useEffect(() => {
+    if (autoStart && enabled && path && returnUrl && profileId && !startedRef.current) {
+      startedRef.current = true;
+      mutate(undefined);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoStart, enabled, path, returnUrl, profileId]);
+
+  return {
+    result: mutation.data ?? null,
+    clientSecret: mutation.data?.paymentSecret,
+    paymentId: mutation.data?.paymentId,
+    provider: mutation.data?.provider,
+    isStarting: mutation.isPending,
+    error: mutation.error,
+    /**
+     * Manually start (or restart) the payment — for click-driven flows. Pass a
+     * body override (e.g. a freshly-created orderId/returnUrl) that wins over
+     * the hook's static options.
+     */
+    start: (override?: Record<string, unknown>) => {
+      startedRef.current = true;
+      return mutateAsync(override);
+    },
+  };
+}

package/src/data/queries/usePaymentLink.ts

@@ -0,0 +1,47 @@
+import type { PaymentLinkData } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+/** A single public payment link by id. */
+export function usePaymentLink(paymentLinkId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaymentLinkData>({
+    queryKey: ["payment-link", paymentLinkId, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/payment-links/${paymentLinkId}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!paymentLinkId,
+  });
+}
+
+export type PaymentLinkFinalizeResult = {
+  id: string;
+  recipientName: string;
+  recipientEmail: string;
+  amount: string;
+  currency: string;
+  message: string | null;
+  status: string;
+  paidAt: string | null;
+  profileName: string;
+};
+
+/** Finalize a payment-link payment on the return page (idempotent reconcile). */
+export function usePaymentLinkFinalize(paymentLinkId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaymentLinkFinalizeResult>({
+    queryKey: ["payment-link-finalize", paymentLinkId, profileId],
+    queryFn: async () => {
+      const res = await client.post(`/public/payment-links/${paymentLinkId}/finalize`, {
+        profileId,
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!paymentLinkId,
+  });
+}

package/src/data/queries/usePodcast.ts

@@ -0,0 +1,85 @@
+"use client";
+import type { BlogPost, BlogCategory, PodcastShow } from "../../types/models";
+import type { AudioTrack } from "../../contexts/AudioPlayerContext";
+import { useForge } from "../../provider/ForgeProvider";
+import { useBlogCategory, useBlogCategoryPosts } from "./useBlog";
+import { useQuery } from "@tanstack/react-query";
+
+// A podcast is a podcast-type blog category; an episode is one of its audio posts.
+// These hooks compose the existing blog hooks so the whole thing rides the proven
+// blog + audio harness.
+
+/** The audio file of an episode (the first audio media), or undefined. */
+export function episodeAudio(post: BlogPost): { url: string; durationSec?: number | null } | undefined {
+  const audio = post.media?.find((m) => (m.type || "").startsWith("audio"));
+  return audio ? { url: audio.url, durationSec: audio.durationSec ?? null } : undefined;
+}
+
+/** True when a post is a real episode (has an audio file). */
+export function isEpisode(post: BlogPost): boolean {
+  return !!episodeAudio(post);
+}
+
+/** Map an episode to an AudioTrack for the shared AudioPlayer / queue. */
+export function episodeToTrack(post: BlogPost, show?: { title?: string; author?: string | null; coverImage?: { url: string } | null } | null): AudioTrack | null {
+  const audio = episodeAudio(post);
+  if (!audio) return null;
+  return {
+    id: post.id,
+    title: post.title,
+    artist: show?.author ?? show?.title ?? undefined,
+    coverImage: show?.coverImage?.url ?? undefined,
+    url: audio.url,
+    duration: audio.durationSec ?? undefined,
+  };
+}
+
+/** All podcast shows for the profile (newest first). */
+export function usePodcasts(options?: { initialData?: PodcastShow[] }) {
+  const { client, profileId } = useForge();
+  return useQuery<PodcastShow[]>({
+    queryKey: ["podcasts-public", profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/blog/posts/podcasts`, { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+    initialData: options?.initialData,
+  });
+}
+
+export interface UsePodcastResult {
+  show: BlogCategory | null;
+  episodes: BlogPost[];
+  isLoading: boolean;
+}
+
+/** A single podcast show (by slug) + its episodes (audio posts), in feed order. */
+export function usePodcast(
+  slug?: string,
+  options?: { initialShow?: BlogCategory | null; initialEpisodes?: BlogPost[] },
+): UsePodcastResult {
+  const showQ = useBlogCategory(slug, { initialData: options?.initialShow });
+  const postsQ = useBlogCategoryPosts(slug, { page: 1, limit: 100 });
+
+  const rawPosts = postsQ.data?.data ?? options?.initialEpisodes ?? [];
+  const episodes = rawPosts.filter(isEpisode);
+
+  return {
+    show: showQ.data ?? options?.initialShow ?? null,
+    episodes,
+    isLoading: showQ.isLoading || (postsQ.isLoading && !options?.initialEpisodes),
+  };
+}
+
+/** Locate one episode within a show by slug, with its neighbours for prev/next. */
+export function findEpisode(episodes: BlogPost[], episodeSlug?: string) {
+  const index = episodeSlug ? episodes.findIndex((e) => e.slug === episodeSlug) : -1;
+  const episode = index >= 0 ? episodes[index] : null;
+  return {
+    episode,
+    index,
+    previous: index > 0 ? episodes[index - 1] : null,
+    next: index >= 0 && index < episodes.length - 1 ? episodes[index + 1] : null,
+  };
+}

package/src/data/queries/usePostCollections.ts

@@ -0,0 +1,48 @@
+import type { IPublicPostCollection, PaginatedData } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+export interface GetPostCollectionsParams {
+  query?: string;
+  page?: number;
+}
+
+export function useGetPostCollections(params?: GetPostCollectionsParams) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<IPublicPostCollection>>({
+    queryKey: ["post-collections", profileId, params],
+    queryFn: async () => {
+      const res = await client.get("/public/post-collections", {
+        params: {
+          profileId: profileId,
+          page: params?.page || 1,
+          limit: 10,
+          filter: {
+            query: params?.query,
+          },
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+export function useGetPostCollection(collectionId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IPublicPostCollection>({
+    queryKey: ["post-collection", profileId, collectionId],
+    queryFn: async () => {
+      const res = await client.get(`/public/post-collections/${collectionId}`, {
+        params: {
+          profileId: profileId,
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!collectionId,
+  });
+}
+

package/src/data/queries/usePosts.ts

@@ -0,0 +1,94 @@
+import type { IPublicPost, PaginatedData } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
+
+export interface GetPostsParams {
+  query?: string;
+  type?: string;
+  membershipTierId?: string;
+  page?: number;
+}
+
+export function useGetPosts(params?: GetPostsParams) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<IPublicPost>>({
+    queryKey: ["posts", profileId, params],
+    queryFn: async () => {
+      const res = await client.get("/public/posts", {
+        params: {
+          profileId: profileId,
+          page: params?.page || 1,
+          limit: 10,
+          filter: {
+            query: params?.query,
+            type: params?.type,
+            membershipTierId: params?.membershipTierId,
+          },
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+export interface GetPostsInfiniteParams {
+  query?: string;
+  type?: string;
+  membershipTierId?: string;
+  pageSize?: number;
+}
+
+/**
+ * Infinite (load-more) variant of `useGetPosts` for the member posts feed.
+ * Same gated endpoint: the server computes per-post `hasAccess` and never
+ * ships media for locked posts, so paging is safe for any auth state.
+ */
+export function useGetPostsInfinite(params?: GetPostsInfiniteParams) {
+  const { client, profileId } = useForge();
+  const limit = params?.pageSize ?? 10;
+
+  return useInfiniteQuery<PaginatedData<IPublicPost>>({
+    queryKey: [
+      "posts-infinite",
+      profileId,
+      { query: params?.query, type: params?.type, membershipTierId: params?.membershipTierId, limit },
+    ],
+    queryFn: async ({ pageParam = 1 }) => {
+      const res = await client.get("/public/posts", {
+        params: {
+          profileId: profileId,
+          page: pageParam,
+          limit,
+          filter: {
+            query: params?.query,
+            type: params?.type,
+            membershipTierId: params?.membershipTierId,
+          },
+        },
+      });
+      return res.data;
+    },
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) => (lastPage.hasNextPage ? (lastPage.nextPage ?? lastPage.page + 1) : undefined),
+    enabled: !!profileId && !!client,
+  });
+}
+
+/**
+ * The member's saved posts (GET /public/posts/saved — requires auth). The
+ * endpoint returns a single `{ data, total }` page.
+ */
+export function useGetSavedPosts(enabled = true) {
+  const { client, profileId } = useForge();
+
+  return useQuery<{ data: IPublicPost[]; total: number }>({
+    queryKey: ["posts-saved", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/posts/saved", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && enabled,
+  });
+}

package/src/data/queries/useProducts.ts

@@ -0,0 +1,108 @@
+import type { IPublicProduct, PaginatedData, ProductCategory } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+export interface GetProductsParams {
+  query?: string;
+  category?: ProductCategory[];
+  page?: number;
+  releaseType?: string;
+}
+
+/** Featured products for the profile, optionally filtered by category. */
+export function useFeaturedProducts(category?: ProductCategory) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IPublicProduct[]>({
+    queryKey: ["featured-products", profileId, category],
+    queryFn: async () => {
+      const res = await client.get("/public/products/featured", {
+        params: { profileId, category },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+export function useGetProducts(params?: GetProductsParams, enabled = true) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<IPublicProduct>>({
+    queryKey: ["products", profileId, params],
+    queryFn: async () => {
+      const res = await client.get("/public/products", {
+        params: {
+          profileId: profileId,
+          category: params?.category,
+          page: params?.page || 1,
+          limit: 10,
+          filter: {
+            query: params?.query,
+            releaseType: params?.releaseType,
+          },
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && enabled,
+  });
+}
+
+export function useGetProduct(productId?: string, options?: { initialData?: IPublicProduct }) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IPublicProduct>({
+    queryKey: ["products", profileId, { productId }],
+    queryFn: async () => {
+      const res = await client.get(`/public/products/${productId}`, {
+        params: {
+          profileId: profileId,
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!productId,
+    initialData: options?.initialData,
+  });
+}
+
+export function useGetProductsByIds(productIds: string[]) {
+  const { client, profileId } = useForge();
+  const idsKey = productIds.join(",");
+
+  return useQuery<IPublicProduct[]>({
+    queryKey: ["products", "batch", profileId, idsKey],
+    queryFn: async () => {
+      const res = await client.get("/public/products/batch", {
+        params: {
+          profileId: profileId,
+          ids: idsKey,
+        },
+      });
+      // Preserve the order of the requested IDs
+      const data = res.data as IPublicProduct[];
+      return productIds
+        .map((id) => data.find((p) => p.id === id))
+        .filter((p): p is IPublicProduct => p != null);
+    },
+    enabled: !!profileId && !!client && productIds.length > 0,
+  });
+}
+
+export function useGetProductCategories() {
+  const { client, profileId } = useForge();
+
+  return useQuery<{ title: ProductCategory; description: string }[]>({
+    queryKey: ["product-categories", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/products/categories", {
+        params: {
+          profileId: profileId,
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}

package/src/data/queries/useReplay.ts

@@ -0,0 +1,19 @@
+import type { ReplayData } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+/** Replay broadcasts for an event ticket id. */
+export function useReplayBroadcasts(ticketId?: string | null) {
+  const { client, profileId } = useForge();
+
+  return useQuery<ReplayData>({
+    queryKey: ["replay-broadcasts", ticketId],
+    queryFn: async () => {
+      const res = await client.get(`/public/broadcasts/replay/${ticketId}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!client && !!ticketId && !!profileId,
+  });
+}