@tribe-nest/forge 1.13.0

package/src/data/queries/useReviews.ts

@@ -0,0 +1,122 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+import type {
+  IPublicReviewsPage,
+  IReviewRequestContext,
+  ISubmittedReview,
+  ReviewEntityType,
+  ReviewSortOption,
+} from "../../types/models";
+
+export interface GetPublicReviewsParams {
+  entityType: ReviewEntityType;
+  entityId: string;
+  page?: number;
+  limit?: number;
+  sort?: ReviewSortOption;
+}
+
+/** Published reviews (+ aggregate) for an entity — GET /public/reviews. */
+export function usePublicReviews(params: GetPublicReviewsParams, enabled = true) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IPublicReviewsPage>({
+    queryKey: [
+      "public-reviews",
+      profileId,
+      params.entityType,
+      params.entityId,
+      params.page ?? 1,
+      params.limit ?? 10,
+      params.sort ?? "recent",
+    ],
+    queryFn: async () => {
+      const res = await client.get("/public/reviews", {
+        params: {
+          profileId,
+          entityType: params.entityType,
+          entityId: params.entityId,
+          page: params.page ?? 1,
+          limit: params.limit ?? 10,
+          sort: params.sort ?? "recent",
+        },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!params.entityId && enabled,
+    placeholderData: (prev) => prev,
+  });
+}
+
+/** Review-form context behind an emailed token link — GET /public/reviews/request/:token. */
+export function useReviewRequest(token?: string) {
+  const { client } = useForge();
+
+  return useQuery<IReviewRequestContext>({
+    queryKey: ["review-request", token],
+    queryFn: async () => {
+      const res = await client.get(`/public/reviews/request/${token}`);
+      return res.data;
+    },
+    enabled: !!client && !!token,
+    retry: false,
+  });
+}
+
+export interface SubmitReviewInput {
+  /** Token from the emailed review request (proves the purchase). */
+  token?: string;
+  /** Fallback path (no token): entity + email/authed account. */
+  profileId?: string;
+  entityType?: ReviewEntityType;
+  entityId?: string;
+  email?: string;
+  rating: number;
+  title?: string | null;
+  body?: string | null;
+  reviewerName?: string | null;
+}
+
+/** Submit (or edit within the window) a review — POST /public/reviews. */
+export function useSubmitReview() {
+  const { client } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<ISubmittedReview, unknown, SubmitReviewInput>({
+    mutationFn: async (input) => {
+      const res = await client.post("/public/reviews", input);
+      return res.data;
+    },
+    onSuccess: (review, variables) => {
+      queryClient.invalidateQueries({ queryKey: ["public-reviews"] });
+      if (variables.token) {
+        queryClient.invalidateQueries({ queryKey: ["review-request", variables.token] });
+      }
+      return review;
+    },
+  });
+}
+
+/** Mark a review helpful (logged-in members) — POST /public/reviews/:id/helpful. */
+export function useAddHelpfulVote() {
+  const { client } = useForge();
+
+  return useMutation<{ helpfulCount: number }, unknown, { reviewId: string }>({
+    mutationFn: async ({ reviewId }) => {
+      const res = await client.post(`/public/reviews/${reviewId}/helpful`);
+      return res.data;
+    },
+  });
+}
+
+/** Withdraw a helpful vote — DELETE /public/reviews/:id/helpful. */
+export function useRemoveHelpfulVote() {
+  const { client } = useForge();
+
+  return useMutation<{ helpfulCount: number }, unknown, { reviewId: string }>({
+    mutationFn: async ({ reviewId }) => {
+      const res = await client.delete(`/public/reviews/${reviewId}/helpful`);
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useShipping.ts

@@ -0,0 +1,109 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+export type ShippingCountry = {
+  name: string;
+  code: string;
+  region: string;
+  states?: { name: string; code: string }[];
+};
+
+export type ShippingRate = {
+  rateId: string;
+  carrier: string;
+  service: string;
+  amount: number;
+  currency: string;
+  estimatedDays: number | null;
+  shipmentId: string;
+};
+
+/**
+ * A shippable group in the checkout. Physical items are grouped by how they
+ * ship: `external` (one combined cost), per-product `flat`, and one `dynamic`
+ * carrier-rated shipment (all dynamic items packed into the seller's boxes → one
+ * carrier choice). `flat`/`external` are auto-selected (single rate); `dynamic`
+ * (`selectable`) is the buyer's carrier choice.
+ */
+export type ShippingGroup = {
+  id: string;
+  type: "flat" | "dynamic" | "external";
+  title: string;
+  productIds: string[];
+  selectable: boolean;
+  rates: ShippingRate[];
+};
+
+/** Countries the profile ships physical products to. */
+export function useShippingCountries() {
+  const { client } = useForge();
+
+  return useQuery<ShippingCountry[]>({
+    queryKey: ["shipping-countries"],
+    queryFn: async () => {
+      const res = await client.get("/public/products/shipping-countries");
+      return res.data;
+    },
+    enabled: !!client,
+  });
+}
+
+export type ShippingRateCartItem = {
+  productId: string;
+  productVariantId: string;
+  quantity: number;
+};
+
+/** Compute shipping rates for an address + cart. */
+export function useShippingRates() {
+  const { client, profileId } = useForge();
+
+  return useMutation<
+    { groups: ShippingGroup[] },
+    unknown,
+    {
+      shippingAddress: { address1: string; city: string; stateCode: string; countryCode: string; zip: string; phone?: string };
+      cartItems: ShippingRateCartItem[];
+    }
+  >({
+    mutationFn: async ({ shippingAddress, cartItems }) => {
+      const res = await client.post("/public/orders/shipping-rates", {
+        profileId,
+        shippingAddress,
+        cartItems,
+      });
+      return res.data;
+    },
+  });
+}
+
+export type ApplyCouponResult = {
+  coupon: { code: string; discountType: string | null; discountValue: number | null } | null;
+  discountAmount: number;
+  chargedAmount: number;
+  chargedCurrency: string;
+  paymentSecret?: string;
+  paymentId?: string;
+  /** Re-quoted sales tax for the re-issued payment intent (display only). */
+  taxQuote?: import("../../types/models").PublicTaxQuote;
+};
+
+/**
+ * Apply (or, with no couponCode, clear) a coupon on an order. Re-issues the
+ * payment intent, so the result carries the updated paymentSecret/paymentId.
+ */
+export function useApplyCoupon() {
+  const { client, profileId } = useForge();
+
+  return useMutation<ApplyCouponResult, unknown, { orderId: string; couponCode?: string; returnUrl: string }>({
+    mutationFn: async ({ orderId, couponCode, returnUrl }) => {
+      const res = await client.post("/public/orders/apply-coupon", {
+        orderId,
+        profileId,
+        couponCode,
+        returnUrl,
+      });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useSubscriptions.ts

@@ -0,0 +1,66 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation } from "@tanstack/react-query";
+
+export type CreateSubscriptionInput = {
+  amount?: number;
+  billingCycle: "month" | "year";
+  membershipTierId: string;
+  returnUrl: string;
+  attributionRefId?: string;
+};
+
+/** Create a paid membership subscription (returns the payment client secret). */
+export function useCreateSubscription() {
+  const { client, profileId } = useForge();
+
+  return useMutation<{ subscriptionId: string; clientSecret: string }, unknown, CreateSubscriptionInput>({
+    mutationFn: async (body) => {
+      const res = await client.post("/public/payments/subscriptions", { ...body, profileId });
+      return res.data;
+    },
+  });
+}
+
+/** Activate a free membership tier. */
+export function useCreateFreeSubscription() {
+  const { client, profileId } = useForge();
+
+  return useMutation<unknown, unknown, { membershipTierId: string; attributionRefId?: string }>({
+    mutationFn: async (body) => {
+      const res = await client.post("/public/payments/subscriptions/free", { ...body, profileId });
+      return res.data;
+    },
+  });
+}
+
+/** Cancel the member's active paid subscription. */
+export function useCancelMembership() {
+  const { client, profileId } = useForge();
+
+  return useMutation<unknown, unknown, { membershipId: string }>({
+    mutationFn: async ({ membershipId }) => {
+      const res = await client.post("/public/payments/subscriptions/cancel", {
+        membershipId,
+        profileId,
+      });
+      return res.data;
+    },
+  });
+}
+
+/**
+ * Reconcile the most recent subscription after a checkout return.
+ * Returns the latest subscription status (e.g. "active").
+ */
+export function useConfirmLatestSubscription() {
+  const { client, profileId } = useForge();
+
+  return useMutation<{ status: string }, unknown, void>({
+    mutationFn: async () => {
+      const res = await client.post("/public/payments/subscriptions/confirm-latest", {
+        profileId,
+      });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useWebsite.ts

@@ -0,0 +1,128 @@
+import type { WebPage } from "../../types";
+import { useForge } from "../../provider/ForgeProvider";
+import { useInitialSiteConfig } from "../../provider/SiteConfigProvider";
+import { keepPreviousData, useMutation, useQuery } from "@tanstack/react-query";
+
+export interface SiteConfig {
+  /** The tenant's settlement currency (e.g. "USD") — the currency API amounts
+   * are in and payments are charged in. */
+  currency: string;
+  /** Sales-tax display mode: true = listing prices already contain tax
+   * ("incl. VAT" style, EU/UK), false/absent = tax added at checkout (US).
+   * Display-only — checkout totals come from the authoritative taxQuote. */
+  pricesIncludeTax?: boolean;
+  metaPixelId: string | null;
+  stripeAccountId: string | null;
+  paystackAccountId: string | null;
+  paymentProviderName: string | null;
+  paymentProviderPublicKey: string | null;
+  /** The single PLATFORM Stripe publishable key. Stripe is Connect, so forge
+   * initialises `loadStripe(stripePublishableKey, { stripeAccount: stripeAccountId })`. */
+  stripePublishableKey: string | null;
+  /** Whether Altcha proof-of-work bot protection is active. Self-hosted, so it
+   * works on every tenant subdomain + custom domain with no per-domain config. */
+  altchaEnabled?: boolean;
+  /** The creator's site display name — the manifest `name` fallback when the
+   * PWA identity has no explicit name. */
+  siteName?: string | null;
+  /** The profile-level PWA identity (icons/name/screenshots) used to build the
+   * installable manifest + head tags. `null` when the creator has no pwaConfig
+   * (minimal name-only manifest, not installable). Screenshots are optional. */
+  pwa?: PwaConfig | null;
+}
+
+/** The PWA identity block on `site-config` (mirrors `pwaConfig` on the profile). */
+export interface PwaConfig {
+  name: string;
+  shortName: string;
+  description: string;
+  icon96: string;
+  icon192: string;
+  icon512: string;
+  screenshotWide1280X720?: string;
+  screenshotNarrow750X1334?: string;
+}
+
+/**
+ * The tenant's mutable runtime config (settlement currency, Meta Pixel id,
+ * payment provider). Fetched at runtime — NOT baked into the build — so a
+ * creator can change these in settings and the live site reflects them without
+ * a rebuild/redeploy.
+ *
+ * If a `<SiteConfigProvider>` seeded an SSR-fetched value (see `fetchSiteConfig`
+ * in `@tribe-nest/forge/server`), it's used as `initialData` so the config is
+ * present on the first render — no client-fetch flash, no hydration mismatch.
+ * An explicit `initialData` override still wins.
+ */
+export function useSiteConfig(opts?: { initialData?: SiteConfig }) {
+  const { client, profileId } = useForge();
+  const ssrInitial = useInitialSiteConfig();
+
+  return useQuery<SiteConfig>({
+    queryKey: ["site-config", profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/websites/site-config", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!client && !!profileId,
+    initialData: opts?.initialData ?? ssrInitial,
+    staleTime: 1000 * 60 * 5, // 5 min — settings change rarely; refetch keeps it fresh
+  });
+}
+
+/**
+ * The store's tax display mode from site config: true = prices shown to the
+ * buyer already include tax (inclusive/EU display), false = tax is added at
+ * checkout (exclusive/US display). Defaults to false until config loads.
+ * Feed this into `<PriceDisplay pricesIncludeTax={...}>`.
+ */
+export function usePricesIncludeTax(): boolean {
+  const { data } = useSiteConfig();
+  return data?.pricesIncludeTax ?? false;
+}
+
+// Tax-aware price rendering primitive, re-exported here (a file the root barrel
+// already star-exports) so `@tribe-nest/frontend-shared` and app code can import
+// it from "@tribe-nest/forge". Its home is `ui/format/PriceDisplay` — the
+// `forge/ui` barrel should export it from there as well.
+export {
+  PriceDisplay,
+  priceTaxCaption,
+  summarizeTaxQuote,
+  type PriceDisplayProps,
+} from "../../ui/format/PriceDisplay";
+
+/** Submit the website contact form. */
+export function useSubmitContactForm() {
+  const { client, profileId } = useForge();
+
+  return useMutation<unknown, unknown, { name: string; email: string; message: string; joinEmailList?: boolean }>({
+    mutationFn: async (body) => {
+      const res = await client.post("/public/websites/contact", { ...body, profileId });
+      return res.data;
+    },
+  });
+}
+
+/**
+ * The rendered web page for a pathname — either the published site (by
+ * subdomain) or a preview (by token). Keeps the previous page during navigation
+ * to avoid a white flash.
+ */
+export function useGetWebPage(pathname: string, opts?: { subdomain?: string; previewToken?: string | null }) {
+  const { client } = useForge();
+  const { subdomain, previewToken } = opts ?? {};
+
+  return useQuery<WebPage>({
+    queryKey: ["web-page", subdomain, pathname, previewToken],
+    queryFn: async () => {
+      const url = previewToken
+        ? `/public/websites/preview?token=${previewToken}&pathname=${pathname}`
+        : `/public/websites?subdomain=${subdomain}&pathname=${pathname}`;
+      const res = await client.get(url);
+      return res.data;
+    },
+    enabled: !!client && (!!previewToken || !!subdomain),
+    placeholderData: keepPreviousData,
+  });
+}

package/src/data/queries/useWebsiteAgent.ts

@@ -0,0 +1,100 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+export interface WebsiteAgentConfig {
+  enabled: boolean;
+  displayName?: string;
+  greeting?: string | null;
+  allowAnonymous?: boolean;
+  allowOrderLookup?: boolean;
+  allowLeadCapture?: boolean;
+}
+
+/** Widget bootstrap config for the profile. When `enabled` is false the widget
+ * should render nothing. */
+export function useWebsiteAgentConfig() {
+  const { client, profileId } = useForge();
+  return useQuery<WebsiteAgentConfig>({
+    queryKey: ["website-agent-config", profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/agent/config`, { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+    staleTime: 5 * 60 * 1000,
+  });
+}
+
+export type AgentStreamEvent =
+  | { type: "text_delta"; delta: string }
+  | { type: "tool_use_start"; name: string }
+  | { type: "tool_use_result"; name: string }
+  | { type: "turn_complete" }
+  | { type: "error"; message: string };
+
+/**
+ * Streams a chat turn over SSE using fetch (axios can't stream). Calls
+ * `onEvent` for each parsed event. Returns when the stream ends.
+ */
+export async function streamAgentMessage(params: {
+  apiUrl: string;
+  token?: string | null;
+  profileId: string;
+  visitorId: string;
+  conversationId: string;
+  message: string;
+  onEvent: (ev: AgentStreamEvent) => void;
+  signal?: AbortSignal;
+}): Promise<void> {
+  const res = await fetch(`${params.apiUrl}/public/agent/conversations/${params.conversationId}/messages`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...(params.token ? { authorization: `Bearer ${params.token}` } : {}),
+    },
+    body: JSON.stringify({ profileId: params.profileId, visitorId: params.visitorId, message: params.message }),
+    signal: params.signal,
+  });
+
+  if (!res.body) throw new Error("No response stream");
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const frames = buffer.split("\n\n");
+    buffer = frames.pop() ?? "";
+    for (const frame of frames) {
+      const line = frame.split("\n").find((l) => l.startsWith("data:"));
+      if (!line) continue;
+      const payload = line.slice(5).trim();
+      if (!payload) continue;
+      try {
+        params.onEvent(JSON.parse(payload) as AgentStreamEvent);
+      } catch {
+        /* ignore heartbeats / malformed frames */
+      }
+    }
+  }
+}
+
+/** Creates a visitor conversation, returning its id (or null when disabled). */
+export async function createAgentConversation(params: {
+  apiUrl: string;
+  token?: string | null;
+  profileId: string;
+  visitorId: string;
+}): Promise<{ id: string | null; requiresLogin?: boolean }> {
+  const res = await fetch(`${params.apiUrl}/public/agent/conversations`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...(params.token ? { authorization: `Bearer ${params.token}` } : {}),
+    },
+    body: JSON.stringify({ profileId: params.profileId, visitorId: params.visitorId }),
+  });
+  return res.json();
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+// Forge — the headless React SDK for TribeNest creator sites.
+//
+// Phase 1 (the spine): client factory, root provider, core types.
+// Subsequent phases add providers (auth/cart/audio), data hooks, flow hooks,
+// headless blocks, and SEO — see docs/code-websites-initiative.md.
+
+export { createForgeClient, getForgeWebSocketUrl } from "./client/createForgeClient";
+export type { ForgeClientOptions } from "./client/createForgeClient";
+
+// All-in-one root provider (query + content + auth + cart + audio + site-config
+// + theme). Most sites import just this.
+export { ForgeProvider, type ForgeProviderProps } from "./provider/ForgeAppProvider";
+// Low-level pieces for hand-composing the tree.
+export { ForgeClientProvider, useForge, type ForgeClientProviderProps, type ForgeContextValue } from "./provider/ForgeProvider";
+export { SiteConfigProvider, useInitialSiteConfig } from "./provider/SiteConfigProvider";
+
+// All domain types + enums/consts (models) and WebPage.
+export * from "./types";
+
+// Providers (Phase 2 — moving from frontend-shared into Forge)
+export { AudioPlayerProvider, useAudioPlayer } from "./contexts/AudioPlayerContext";
+export type { AudioTrack } from "./contexts/AudioPlayerContext";
+export { CartProvider, useCart } from "./contexts/CartContext";
+export type { CartItem } from "./contexts/CartContext";
+export {
+  ACCESS_TOKEN_KEY,
+  PUBLIC_ACCESS_TOKEN_KEY,
+  usePublicAuth,
+  PublicAuthProvider,
+  PublicAuthContext,
+} from "./contexts/PublicAuthContext";
+export type { AuthActions } from "./contexts/PublicAuthContext";
+// App-user auth (mini-apps) + the /admin guard.
+export {
+  useAppAuth,
+  AppAuthProvider,
+  APP_ACCESS_TOKEN_KEY,
+  type AppAuthUser,
+  type AppSignupInput,
+  type AppSignupResult,
+} from "./contexts/AppAuthContext";
+export { useAppAdminGuard, type AppAdminGuardResult } from "./contexts/useAppAdminGuard";
+
+// Data hooks (React Query) — Phase 3
+export * from "./data/queries/useProducts";
+export * from "./data/queries/useMembership";
+export * from "./data/queries/useCourses";
+export * from "./data/queries/useCoachingProducts";
+export * from "./data/queries/usePosts";
+export * from "./data/queries/usePostCollections";
+export * from "./data/queries/useBlog";
+export * from "./data/queries/usePodcast";
+export * from "./data/queries/useCollections";
+export * from "./data/queries/useEvents";
+export * from "./data/queries/useInvoice";
+export * from "./data/queries/usePaymentLink";
+export * from "./data/queries/useLeadMagnet";
+export * from "./data/queries/useBlogComments";
+export * from "./data/queries/usePageActions";
+export * from "./data/queries/useForms";
+export * from "./data/queries/useReplay";
+export * from "./data/queries/useCoachingAvailability";
+export * from "./data/queries/useCohortPage";
+export * from "./data/queries/useCourseAccess";
+export * from "./data/queries/useBroadcasts";
+export * from "./data/queries/useAccount";
+export * from "./data/queries/useFinalize";
+export * from "./data/queries/useSubscriptions";
+export * from "./data/queries/useEngagement";
+export * from "./data/queries/usePaymentFlow";
+export * from "./data/queries/useOrders";
+export * from "./data/queries/useAuthActions";
+export * from "./data/queries/useCoupons";
+export * from "./data/queries/useAccountSettings";
+export * from "./data/queries/useDonations";
+export * from "./data/queries/useOffers";
+export * from "./data/queries/useShipping";
+export * from "./data/queries/useWebsite";
+export * from "./data/queries/useWebsiteAgent";
+export * from "./data/queries/useCurrencies";
+export * from "./data/queries/useChat";
+export * from "./data/queries/useAnalytics";
+export * from "./data/queries/useCommunity";
+export * from "./data/queries/useReviews";
+export * from "./data/queries/useDocuments";
+export * from "./data/queries/useNotifications";
+export * from "./data/queries/usePWA";
+export * from "./data/queries/useCertificates";
+
+// Content layer (Phase E) — typed/editable/localizable site content
+export * from "./content";
+
+// Utils
+export * from "./utils/attribution";
+export * from "./utils/landing";
+export * from "./utils/metaPixel";
+export * from "./utils/cookieConsent";
+export * from "./utils/structuredData";