@tribe-nest/forge 3.23.0 → 3.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.23.0",
+  "version": "3.25.0",
   "publishConfig": {
     "access": "public"
   },
@@ -39,6 +39,7 @@
   },
   "devDependencies": {
     "@types/react": "^19.1.2",
+    "simple-icons": "^16.28.0",
     "typescript": "~5.8.3"
   },
   "license": "ISC"

package/src/data/queries/useAnalytics.ts

@@ -62,25 +62,76 @@ export interface TrackEventOptions {
  * `const { track } = useTrackEvent(); track("cta_click", { id: "hero" })`.
  */
 export function useTrackEvent(opts?: TrackEventOptions) {
-  const { client, subdomain: ctxSubdomain } = useForge();
+  const { client, apiUrl, subdomain: ctxSubdomain } = useForge();
   const subdomain = opts?.subdomain ?? ctxSubdomain;
   const storeSession = opts?.storeSession ?? true;
 
-  const track = useCallback(
-    (eventType: string, eventData: Record<string, unknown> = {}) => {
-      if (typeof window === "undefined" || !client || !subdomain) return;
+  const buildPayload = useCallback(
+    (eventData: Record<string, unknown>) => {
       // Cookieless mode omits the sessionId entirely — the backend derives a
       // rotating per-day visitor hash so nothing touches the device.
-      const sessionId = storeSession ? getAnalyticsSessionId(subdomain) : undefined;
+      const sessionId = storeSession && subdomain ? getAnalyticsSessionId(subdomain) : undefined;
       const payload: Record<string, unknown> = { ...eventData };
       if (sessionId) payload.sessionId = sessionId;
+      return payload;
+    },
+    [subdomain, storeSession],
+  );
+
+  const track = useCallback(
+    (eventType: string, eventData: Record<string, unknown> = {}) => {
+      if (typeof window === "undefined" || !client || !subdomain) return;
       // Fire-and-forget: analytics must never block the UI or surface errors.
       client
-        .post("/public/websites/track-event", { subdomain, eventType, eventData: payload })
+        .post("/public/websites/track-event", { subdomain, eventType, eventData: buildPayload(eventData) })
         .catch(() => {});
     },
-    [client, subdomain, storeSession],
+    [client, subdomain, buildPayload],
+  );
+
+  /**
+   * Same event, but it survives the page going away.
+   *
+   * `track` above posts through the Axios instance, and Axios in the browser is
+   * XHR. XHR has no `keepalive` option at all, so when a click navigates the tab
+   * somewhere else the request is cancelled mid-flight and the event is simply
+   * lost. That is tolerable for a click that stays on the site and fatal for one
+   * that does not: on a music smart link EVERY conversion is an outbound
+   * navigation to Spotify, so the ordinary transport would drop a large share of
+   * the only events the page exists to record, and take the server-side Meta
+   * `Lead` down with them.
+   *
+   * `fetch` with `keepalive: true` is the fix. Deliberately not
+   * `navigator.sendBeacon`, which cannot set `Content-Type: application/json`
+   * without wrapping the body in a Blob, and this endpoint is JSON-only.
+   *
+   * Use it for any event immediately followed by a navigation. Ordinary
+   * in-page events should keep using `track`, which goes through the configured
+   * client and picks up its interceptors.
+   */
+  const trackBeacon = useCallback(
+    (eventType: string, eventData: Record<string, unknown> = {}) => {
+      if (typeof window === "undefined" || !apiUrl || !subdomain) return;
+      try {
+        void fetch(`${apiUrl.replace(/\/$/, "")}/public/websites/track-event`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          keepalive: true,
+          body: JSON.stringify({
+            subdomain,
+            eventType,
+            eventData: buildPayload(eventData),
+            // The referrer header only carries the origin cross-origin, so the
+            // server cannot work out which page this happened on by itself.
+            eventSourceUrl: window.location.href,
+          }),
+        }).catch(() => {});
+      } catch {
+        // Best-effort by definition; never disrupt the navigation.
+      }
+    },
+    [apiUrl, subdomain, buildPayload],
   );
 
-  return { track };
+  return { track, trackBeacon };
 }

package/src/data/queries/useMusicLink.ts

@@ -0,0 +1,28 @@
+import type { IMusicLink } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+/**
+ * One music smart link by slug.
+ *
+ * Pass `initialData` from the route loader (`fetchMusicLinkServer`) so the page
+ * renders complete on the server with no client spinner. That is not just a
+ * polish detail here: these links are opened almost entirely from social apps'
+ * in-app browsers on a phone, on the worst connection the fan will use all day,
+ * and a page that shows a spinner before its buttons loses the tap.
+ *
+ * `undefined` while loading, `null` when the link does not exist or is archived.
+ */
+export function useMusicLink(slug?: string, options?: { initialData?: IMusicLink | null }) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IMusicLink | null>({
+    queryKey: ["music-link", profileId, slug],
+    queryFn: async () => {
+      const res = await client.get(`/public/music-links`, { params: { profileId, slug } });
+      return res.data ?? null;
+    },
+    enabled: !!profileId && !!client && !!slug,
+    ...(options?.initialData !== undefined ? { initialData: options.initialData } : {}),
+  });
+}

package/src/index.ts

@@ -77,6 +77,7 @@ export * from "./data/queries/useBlog";
 export * from "./data/queries/usePodcast";
 export * from "./data/queries/useCollections";
 export * from "./data/queries/useEvents";
+export * from "./data/queries/useMusicLink";
 export * from "./data/queries/useEventSeries";
 export * from "./data/queries/useInvoice";
 export * from "./data/queries/usePaymentLink";

package/src/server/index.ts

@@ -34,6 +34,7 @@ export type { ApiProbeResult, ForgeSsrDiagnostics, SsrFetchFailure };
 import type {
   IEvent,
   IEventSeries,
+  IMusicLink,
   IPublicProduct,
   PublicCourse,
   CoachingProduct,
@@ -54,6 +55,9 @@ import {
   type ReviewSchemaReview,
   type SiteSeoContext,
 } from "../utils/structuredData";
+// Also React-free, so it belongs in this entry rather than being re-derived by
+// each route that needs share tags.
+import { buildHeadMeta } from "../utils/headMeta";
 export type { SiteSeoContext };
 import type { SiteConfig } from "../data/queries/useWebsite";
 
@@ -293,6 +297,53 @@ export function fetchEventSeriesServer(opts: {
   });
 }
 
+/**
+ * Fetch a music smart link by slug for SSR.
+ *
+ * `null` means render the not-found state: the slug does not exist for this
+ * profile, or the link is archived. Archiving is how a creator takes a link
+ * down, so a 404 is the correct answer rather than a stale page.
+ */
+export function fetchMusicLinkServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  slug: string;
+}): Promise<IMusicLink | null> {
+  return getJson<IMusicLink>(opts.apiUrl, `/public/music-links`, {
+    profileId: opts.profileId,
+    slug: opts.slug,
+  });
+}
+
+/**
+ * Head tags for a music smart link.
+ *
+ * The share card matters more here than on any other page in the product. A
+ * music link exists to be pasted into an Instagram story, a WhatsApp message or
+ * a tweet, so for most of its audience the OG image and title ARE the page: they
+ * decide whether anyone taps through at all. `og:type` is `music.song` (or
+ * `music.album`) rather than the default `website`, which is what lets a
+ * platform render it as a music card instead of a generic link.
+ */
+export function buildMusicLinkHead(
+  link: Pick<IMusicLink, "title" | "artistName" | "description" | "artworkUrl"> | null,
+  opts?: { canonicalUrl?: string; kind?: "song" | "album" },
+) {
+  if (!link) {
+    return buildHeadMeta({ title: "Link not found", noindex: true });
+  }
+
+  const title = link.artistName ? `${link.artistName} - ${link.title}` : link.title;
+
+  return buildHeadMeta({
+    title,
+    description: link.description || `Listen to ${title} on your favourite streaming service.`,
+    image: link.artworkUrl || undefined,
+    canonicalUrl: opts?.canonicalUrl,
+    ogType: opts?.kind === "album" ? "music.album" : "music.song",
+  });
+}
+
 /** Fetch a single product by id or slug for SSR. */
 export function fetchProductServer(opts: {
   apiUrl: string;

package/src/types/models.ts

@@ -1875,3 +1875,52 @@ export type PaymentLinkData = {
   profileName: string;
   profileSubdomain: string;
 };
+
+/**
+ * A music smart link, as served publicly at `/l/<slug>` on a creator's site.
+ *
+ * This is the PUBLIC shape, which is narrower than the stored row: the backend
+ * builds it field by field, drops disabled destinations, sorts the rest by the
+ * order the creator arranged, and resolves `metaPixelId` from the route's
+ * tracking config (falling back to the profile pixel). No CAPI token is ever
+ * part of it.
+ */
+export interface IMusicLinkDestination {
+  /** A key from the platform allowlist, e.g. `spotify`, `appleMusic`. */
+  platform: string;
+  url: string;
+}
+
+/** Per-link presentation, layered over the site theme by `MusicLinkPage`. */
+export interface IMusicLinkTheme {
+  /**
+   * Which of the five layouts to render. Composition, not colour: the tokens
+   * below tune whichever one is chosen.
+   */
+  style?: "classic" | "immersive" | "split" | "minimal" | "compact";
+  mode?: "light" | "dark";
+  background?: string;
+  text?: string;
+  accent?: string;
+  surface?: string;
+  border?: string;
+  /** Blurred cover behind the page. Defaults to on. */
+  artworkBackdrop?: boolean;
+  buttonShape?: "rounded" | "pill" | "square";
+}
+
+export interface IMusicLink {
+  id: string;
+  slug: string;
+  title: string;
+  artistName: string | null;
+  description: string | null;
+  artworkUrl: string | null;
+  /** 30-second preview, played over the artwork. Apple's, which does not expire. */
+  previewUrl: string | null;
+  releaseDate: string | null;
+  theme: IMusicLinkTheme | null;
+  destinations: IMusicLinkDestination[];
+  /** Public pixel id for this route, or null when neither it nor the profile has one. */
+  metaPixelId: string | null;
+}

package/src/ui/analytics/ForgeAnalytics.tsx

@@ -188,6 +188,17 @@ export function ForgeAnalytics({
       const el = start.closest("a,button,[data-track]") as HTMLElement | null;
       if (!el) return;
 
+      // Opt-out for elements that report their own click.
+      //
+      // This listener cannot know that a component already sent a richer event
+      // for the same click, so without a way to stand down, anything that tracks
+      // its own clicks is counted twice. Worse than the double count: this
+      // listener's payload carries no `eventId`, so the resulting CAPI `Lead`
+      // has nothing to dedupe against, and Meta sees two conversions for one
+      // action. Any element that fires its own event must carry
+      // `data-track-skip`.
+      if (el.closest("[data-track-skip]")) return;
+
       const anchor = el.closest("a") as HTMLAnchorElement | null;
       const text = (el.getAttribute("aria-label") || el.textContent || "").trim().slice(0, 120) || undefined;
       track("click", {
@@ -197,6 +208,10 @@ export function ForgeAnalytics({
         text,
         href: anchor?.href || undefined,
         id: el.id || el.getAttribute("data-track") || undefined,
+        // Page views have carried an id since this shipped; clicks did not, so a
+        // click's server-side CAPI twin had no `event_id` and could never be
+        // deduplicated against a browser pixel event of the same name.
+        eventId: newEventId(),
       });
     };
 

package/src/ui/index.ts

@@ -64,6 +64,7 @@ export { UserMenu, type UserMenuProps } from "./styled/UserMenu";
 export { EmailListForm, type EmailListFormProps } from "./styled/EmailListForm";
 export { BlogComments, type BlogCommentsProps } from "./styled/BlogComments";
 export { PageActions, type PageActionsProps } from "./styled/PageActions";
+export { MusicLinkPage, type MusicLinkPageProps } from "./styled/MusicLinkPage";
 export { BlogPostFooter, type BlogPostFooterProps } from "./styled/BlogPostFooter";
 export { BotProtection, EMPTY_BOT_FIELDS, type BotFields } from "./styled/BotProtection";
 export { ContactForm, type ContactFormProps } from "./styled/ContactForm";