@tribe-nest/forge 3.22.0 → 3.24.0

package/src/data/queries/useSubscriptions.ts

@@ -16,11 +16,38 @@ export type CreateSubscriptionInput = {
   attributionRefId?: string;
 };
 
-/** Create a paid membership subscription (returns the payment client secret). */
+/**
+ * The two things subscribing can produce.
+ *
+ * A member with no live subscription gets a provider session to pay with:
+ * `clientSecret` on Stripe, `accessCode` + `checkoutUrl` on Paystack. A member
+ * who ALREADY subscribes to this artist is changing tier: the server moves their
+ * existing subscription onto the new price with proration, so there is nothing
+ * to pay right now: `requiresPayment` is false, `changed` is true and no
+ * session is issued. Branch on `requiresPayment`, never on the presence of a
+ * secret alone. A Paystack subscription has never had one, and reading its
+ * absence as "nothing to pay" hands out the tier for free.
+ */
+export type CreateSubscriptionResult = {
+  membershipId: string;
+  subscriptionId: string;
+  /** STRIPE ONLY. */
+  clientSecret?: string;
+  /** PAYSTACK ONLY: inline checkout session. */
+  accessCode?: string;
+  /** PAYSTACK ONLY: hosted page, the runtime fallback. */
+  checkoutUrl?: string;
+  currentPeriodStart?: string;
+  currentPeriodEnd?: string;
+  requiresPayment?: boolean;
+  changed?: boolean;
+};
+
+/** Subscribe to a paid tier, or move an existing subscription onto another one. */
 export function useCreateSubscription() {
   const { client, profileId } = useForge();
 
-  return useMutation<{ subscriptionId: string; clientSecret: string }, unknown, CreateSubscriptionInput>({
+  return useMutation<CreateSubscriptionResult, unknown, CreateSubscriptionInput>({
     mutationFn: async (body) => {
       const res = await client.post("/public/payments/subscriptions", { ...body, profileId });
       return res.data;
@@ -40,11 +67,30 @@ export function useCreateFreeSubscription() {
   });
 }
 
-/** Cancel the member's active paid subscription. */
+export type CancelMembershipResult = {
+  membershipId: string;
+  /** The status AFTER cancelling — still `active` while a paid period runs out. */
+  status: string;
+  /** True when the cancellation was scheduled rather than applied immediately. */
+  cancelAtPeriodEnd: boolean;
+  /** ISO date benefits actually stop. Null when they already have. */
+  accessUntil: string | null;
+};
+
+/**
+ * Cancel the member's membership.
+ *
+ * Cancelling a paid, paid-up membership does NOT take effect now: the server
+ * schedules it for the end of the period they have already paid for and the
+ * member keeps their benefits until `accessUntil`. Free tiers (and any
+ * membership with nothing paid up) end immediately. Works for every membership
+ * the member can still use — including one whose card is failing, which used to
+ * be rejected with an error the UI never showed.
+ */
 export function useCancelMembership() {
   const { client, profileId } = useForge();
 
-  return useMutation<unknown, unknown, { membershipId: string }>({
+  return useMutation<CancelMembershipResult, unknown, { membershipId: string }>({
     mutationFn: async ({ membershipId }) => {
       const res = await client.post("/public/payments/subscriptions/cancel", {
         membershipId,

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";
@@ -127,6 +128,11 @@ export * from "./utils/landing";
 export * from "./utils/metaPixel";
 export * from "./utils/cookieConsent";
 export * from "./utils/structuredData";
+// Paystack inline checkout: the ONE implementation of the popup, exported so a
+// hand-rolled payment surface (or `apps/client`) drives it through the same
+// lazy load, the same runtime fallback and the same return-leg navigation
+// rather than growing a second copy.
+export * from "./utils/paystackCheckout";
 // The per-booking checkout credential + where it is kept across the payment
 // redirect. Exported so a host that drives the booking endpoints itself can
 // hold the secret the same way the built-in flows do.

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/server/platform.ts

@@ -376,7 +376,7 @@ export async function handlePlatformEvent(
       ),
       budget,
       `Handler for "${event.event}" took longer than ${budget}ms. Move the slow part into ` +
-        `enqueueAppJob() and return — the platform's delivery attempt times out before this finishes.`,
+        `enqueueAppJob() and return. The platform's delivery attempt times out before this finishes.`,
     );
   } catch (err) {
     // 500 so the platform retries. Writes already made carry keys derived from

package/src/server/platformEvents.generated.ts

@@ -1,4 +1,4 @@
-// GENERATED FILE — DO NOT EDIT.
+// GENERATED FILE. DO NOT EDIT.
 // Produced from the platform event catalog by:
 //   cd apps/backend && npm run generate:forge-events
 //
@@ -10,7 +10,7 @@
 /**
  * Every platform event an app can subscribe to, and the exact body it carries.
  *
- * Delivery is at-least-once — dedupe on `eventId`. The same event WILL arrive
+ * Delivery is at-least-once, so dedupe on `eventId`. The same event WILL arrive
  * again after a retry, and a handler that acts twice will double-send.
  *
  * A body may additionally carry `partial: true`. That means the platform could
@@ -20,7 +20,7 @@
  */
 export type PlatformEventMap = {
   /**
-   * Affiliate applied — Someone applied to the affiliate program.
+   * Affiliate applied: Someone applied to the affiliate program.
    *
    * Requires the `affiliates.read` grant.
    */
@@ -28,7 +28,7 @@ export type PlatformEventMap = {
     affiliateId: string;
   };
   /**
-   * Checkout abandoned — Someone started a checkout and did not finish it.
+   * Checkout abandoned: Someone started a checkout and did not finish it.
    *
    * Requires the `products.read` grant.
    */
@@ -42,7 +42,7 @@ export type PlatformEventMap = {
     currency?: string | null;
   };
   /**
-   * Checkout recovered — An abandoned checkout was completed after all.
+   * Checkout recovered: An abandoned checkout was completed after all.
    *
    * Requires the `products.read` grant.
    */
@@ -56,7 +56,7 @@ export type PlatformEventMap = {
     currency: string | null;
   };
   /**
-   * Collection entry submitted — A visitor submitted an entry to a collection.
+   * Collection entry submitted: A visitor submitted an entry to a collection.
    *
    * Requires the `collections.read` grant.
    */
@@ -67,7 +67,7 @@ export type PlatformEventMap = {
     status?: string | null;
   };
   /**
-   * Community post created — A member posted in a community space.
+   * Community post created: A member posted in a community space.
    *
    * Requires the `community.new_post` grant.
    */
@@ -77,7 +77,7 @@ export type PlatformEventMap = {
     authorAccountId?: string | null;
   };
   /**
-   * Community reply created — A member replied to a community post.
+   * Community reply created: A member replied to a community post.
    *
    * Requires the `community.new_comment` grant.
    */
@@ -89,7 +89,7 @@ export type PlatformEventMap = {
     parentReplyId?: string | null;
   };
   /**
-   * Contact form message — Someone sent a message through a website contact form.
+   * Contact form message: Someone sent a message through a website contact form.
    *
    * Requires the `contacts.read` grant.
    */
@@ -99,7 +99,7 @@ export type PlatformEventMap = {
     message?: string | null;
   };
   /**
-   * Form submitted — A form was submitted. Carries the submission id — read the answers through the platform client.
+   * Form submitted: A form was submitted. Carries the submission id. Read the answers through the platform client.
    *
    * Requires the `forms.read` grant.
    */
@@ -110,7 +110,7 @@ export type PlatformEventMap = {
     contactId: string | null;
   };
   /**
-   * Quiz completed — A contact completed a graded form, with their score and outcome.
+   * Quiz completed: A contact completed a graded form, with their score and outcome.
    *
    * Requires the `contacts.read` grant.
    */
@@ -124,7 +124,7 @@ export type PlatformEventMap = {
     outcomeKey?: string | null;
   };
   /**
-   * Tag added to contact — A tag was applied to a contact.
+   * Tag added to contact: A tag was applied to a contact.
    *
    * Requires the `contacts.read` grant.
    */
@@ -133,7 +133,7 @@ export type PlatformEventMap = {
     tagId: string;
   };
   /**
-   * Course completed — A learner finished a course.
+   * Course completed: A learner finished a course.
    *
    * Requires the `courses.read` grant.
    */
@@ -145,7 +145,7 @@ export type PlatformEventMap = {
     completedAt: string | null;
   };
   /**
-   * Lesson progressed — A learner completed a lesson.
+   * Lesson progressed: A learner completed a lesson.
    *
    * Requires the `courses.read` grant.
    */
@@ -157,7 +157,7 @@ export type PlatformEventMap = {
     cohortId?: string | null;
   };
   /**
-   * Payment disputed — A customer disputed a payment (chargeback).
+   * Payment disputed: A customer disputed a payment (chargeback).
    *
    * Requires the `income.read` grant.
    */
@@ -167,7 +167,7 @@ export type PlatformEventMap = {
     reason?: string | null;
   };
   /**
-   * Document signed or decided — A proposal or contract was signed, accepted or declined.
+   * Document signed or decided: A proposal or contract was signed, accepted or declined.
    *
    * Requires the `deals.read` grant.
    */
@@ -178,7 +178,7 @@ export type PlatformEventMap = {
     kind?: string | null;
   };
   /**
-   * Email link clicked — A recipient clicked a link in a marketing email.
+   * Email link clicked: A recipient clicked a link in a marketing email.
    *
    * Requires the `emails.read` grant.
    */
@@ -189,7 +189,7 @@ export type PlatformEventMap = {
     occurredAt?: string | null;
   };
   /**
-   * Email opened — A recipient opened a marketing email.
+   * Email opened: A recipient opened a marketing email.
    *
    * Requires the `emails.read` grant.
    */
@@ -199,7 +199,7 @@ export type PlatformEventMap = {
     occurredAt?: string | null;
   };
   /**
-   * Event tickets bought — Someone paid for tickets to an event.
+   * Event tickets bought: Someone paid for tickets to an event.
    *
    * Requires the `events.read` grant.
    */
@@ -221,7 +221,7 @@ export type PlatformEventMap = {
     }>;
   };
   /**
-   * Membership tier archived — A membership tier was archived and can no longer be joined.
+   * Membership tier archived: A membership tier was archived and can no longer be joined.
    *
    * Requires the `membership.tier_archived` grant.
    */
@@ -231,7 +231,7 @@ export type PlatformEventMap = {
     archived: boolean;
   };
   /**
-   * Membership tier created — A new membership tier was published.
+   * Membership tier created: A new membership tier was published.
    *
    * Requires the `membership.tier_created` grant.
    */
@@ -244,7 +244,7 @@ export type PlatformEventMap = {
     archived: boolean;
   };
   /**
-   * Inbound message — An SMS or WhatsApp message arrived from a contact.
+   * Inbound message: An SMS or WhatsApp message arrived from a contact.
    *
    * Requires the `contacts.read` grant.
    */
@@ -257,7 +257,7 @@ export type PlatformEventMap = {
     occurredAt?: string | null;
   };
   /**
-   * Content reported — A member reported community content for moderation.
+   * Content reported: A member reported community content for moderation.
    *
    * Requires the `community.content_reported` grant.
    */
@@ -267,7 +267,7 @@ export type PlatformEventMap = {
     entityType?: string | null;
   };
   /**
-   * Order paid — A store order was paid for. Carries the order, its line items and a buyer reference.
+   * Order paid: A store order was paid for. Carries the order, its line items and a buyer reference.
    *
    * Requires the `products.read` grant.
    */
@@ -291,7 +291,7 @@ export type PlatformEventMap = {
     }>;
   };
   /**
-   * Payout settled — A payout to the creator's bank account settled.
+   * Payout settled: A payout to the creator's bank account settled.
    *
    * Requires the `income.read` grant.
    */
@@ -302,7 +302,7 @@ export type PlatformEventMap = {
     currency: string;
   };
   /**
-   * Member post published — A post was published to the member feed, with the tiers that can see it.
+   * Member post published: A post was published to the member feed, with the tiers that can see it.
    *
    * Requires the `membership.new_post` grant.
    */
@@ -311,7 +311,7 @@ export type PlatformEventMap = {
     membershipTiers?: Array<unknown> | null;
   };
   /**
-   * Refund failed — A refund could not be completed.
+   * Refund failed: A refund could not be completed.
    *
    * Requires the `income.read` grant.
    */
@@ -324,7 +324,7 @@ export type PlatformEventMap = {
     sourceId?: string | null;
   };
   /**
-   * Refund succeeded — A refund completed.
+   * Refund succeeded: A refund completed.
    *
    * Requires the `income.read` grant.
    */
@@ -336,7 +336,7 @@ export type PlatformEventMap = {
     capturedCents?: number | null;
   };
   /**
-   * Review submitted — A customer left a review, with its rating and moderation status.
+   * Review submitted: A customer left a review, with its rating and moderation status.
    *
    * Requires the `reviews.read` grant.
    */
@@ -350,7 +350,7 @@ export type PlatformEventMap = {
     isEdit?: boolean | null;
   };
   /**
-   * Review published — A review passed moderation and is now public.
+   * Review published: A review passed moderation and is now public.
    *
    * Requires the `reviews.read` grant.
    */
@@ -358,7 +358,7 @@ export type PlatformEventMap = {
     reviewId: string;
   };
   /**
-   * Shipment status changed — A shipment for an order moved — dispatched, in transit, delivered.
+   * Shipment status changed: A shipment for an order moved: dispatched, in transit, delivered.
    *
    * Requires the `products.read` grant.
    */
@@ -371,7 +371,7 @@ export type PlatformEventMap = {
     carrier?: string | null;
   };
   /**
-   * Website published — A website was published.
+   * Website published: A website was published.
    *
    * Requires the `websites.read` grant.
    */
@@ -418,5 +418,5 @@ export const PLATFORM_EVENT_PERMISSIONS: Record<PlatformEventName, string> = {
   "website.published": "websites.read",
 };
 
-/** Every event name, in one array — handy for building a UI or validating input. */
+/** Every event name, in one array, handy for building a UI or validating input. */
 export const PLATFORM_EVENT_NAMES = Object.keys(PLATFORM_EVENT_PERMISSIONS) as PlatformEventName[];

package/src/server/pwa.ts

@@ -242,7 +242,7 @@ export function buildPwaHead(opts: BuildPwaHeadOptions): PwaHead {
  */
 export function forgeServiceWorkerScript(version: string = FORGE_PWA_VERSION): string {
   const cacheName = `forge-pwa-v${version}`;
-  return `// Auto-generated Forge service worker (v${version}). Do not edit — served by /sw.js.
+  return `// Auto-generated Forge service worker (v${version}). Do not edit. Served by /sw.js.
 const CACHE = ${JSON.stringify(cacheName)};
 const OFFLINE_URL = "/offline";
 
@@ -312,7 +312,7 @@ self.addEventListener("push", (event) => {
     };
     event.waitUntil(self.registration.showNotification(title, options));
   } catch (err) {
-    // swallow — a malformed push must not crash the SW
+    // swallow: a malformed push must not crash the SW
   }
 });
 

package/src/types/models.ts

@@ -57,13 +57,34 @@ export type PublicTaxQuote = {
 /**
  * Superset response of the `/public/<domain>/.../start-payment` endpoint family.
  * Each domain (orders, events, coaching, courses, invoices, payment-links,
- * donations) returns the same core — paymentSecret + paymentId + a provider —
- * plus its own optional extras. The provider field is named inconsistently
- * across domains (`paymentProvider` vs `paymentProviderName`); usePaymentFlow
- * normalizes it to `provider`.
+ * donations) returns the same core (paymentId, a provider, and that provider's
+ * session) plus its own optional extras. The provider field is named
+ * inconsistently across domains (`paymentProvider` vs `paymentProviderName`);
+ * usePaymentFlow normalizes it to `provider`.
+ *
+ * The session field is provider-specific and the two never overlap:
+ * Stripe always populates `paymentSecret` and never the Paystack pair; Paystack
+ * always populates `accessCode` + `checkoutUrl` and never `paymentSecret`.
  */
 export type PaymentStartResponse = {
-  paymentSecret: string;
+  /**
+   * STRIPE ONLY: the PaymentIntent client secret fed to Stripe Elements.
+   * Optional on the type because Paystack has no equivalent; still ALWAYS
+   * populated by the Stripe branch, whose meaning is frozen.
+   */
+  paymentSecret?: string;
+  /**
+   * PAYSTACK ONLY: the checkout-session access code from
+   * `/transaction/initialize`, handed to the inline modal. Carries the session,
+   * so no public key is involved.
+   */
+  accessCode?: string;
+  /**
+   * PAYSTACK ONLY: the hosted checkout URL from the SAME initialize response.
+   * The RUNTIME fallback used when the modal cannot open, never a version
+   * fallback.
+   */
+  checkoutUrl?: string;
   paymentId: string;
   paymentProvider?: PaymentProviderName;
   paymentProviderName?: PaymentProviderName;
@@ -1248,8 +1269,34 @@ export type ITicket = {
   quantity: number;
   order: number;
   sold: number;
+  /**
+   * Seats promised to somebody else's IN-FLIGHT checkout — not yet sold, but
+   * not on the table either.
+   *
+   * The server sells on `quantity - sold - held` (`inventoryHold.ts`), so a
+   * surface that shows `quantity - sold` tells a fan "3 left" about seats that
+   * are in other people's carts and then refuses them at reserve. Use
+   * `ticketSeatsAvailable` from `@tribe-nest/forge/ui` rather than subtracting
+   * by hand — it is the one place the two stacks agree with the server.
+   *
+   * Optional, and absent means zero: a site pinned to an API build that
+   * predates the hold engine keeps its previous behaviour instead of reading
+   * every tier as sold out.
+   */
+  held?: number;
   maxPerPerson: number;
   expiresAt?: string;
+  /**
+   * Scheduled on-sale. Before this instant the server refuses the tier with
+   * `ticket_not_yet_on_sale` — `evaluateTierSellability` is the authority.
+   *
+   * The tier stays VISIBLE on purpose: "on sale Friday 10am" is information a
+   * fan wants, and hiding it makes a scheduled on-sale indistinguishable from
+   * the tier not existing. So a renderer must announce the time and refuse the
+   * add, exactly as it does for a members-only tier — see `ticketSaleWindow`
+   * and `onSaleBadge` in `@tribe-nest/forge/ui`.
+   */
+  availableFrom?: string | null;
   archivedAt?: string;
   /**
    * This tier is not listed publicly (1.2). If you are looking at one, it is
@@ -1828,3 +1875,45 @@ 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 {
+  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;
+  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/types/paystack-inline.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Minimal typings for `@paystack/inline-js` v2, which ships no declarations of
+ * its own (no `types` field, no bundled `.d.ts`).
+ *
+ * This file is pulled into every consuming program by an explicit
+ * `/// <reference path>` in `utils/paystackCheckout.ts` rather than by living in
+ * a `typeRoots` directory. Forge ships SOURCE, so a site (or `apps/client`)
+ * type-checks these files inside its own program, and an ambient declaration
+ * that is merely present in the package is not part of that program unless
+ * something in the import graph reaches it.
+ *
+ * Only the surface Forge actually calls is described. Widening it is fine;
+ * guessing at shapes we never call is not.
+ */
+declare module "@paystack/inline-js" {
+  /** What Paystack hands back on a completed transaction. */
+  export interface PaystackTransaction {
+    /** Our own `paymentId` UUID: the reference `startCharge` minted. */
+    reference?: string;
+    /** Paystack's echo of the same reference on the callback URL. */
+    trxref?: string;
+    /** Paystack's internal numeric transaction id, as a string. */
+    transaction?: string;
+    status?: string;
+    message?: string;
+  }
+
+  export interface PaystackResumeOptions {
+    onSuccess?: (transaction: PaystackTransaction) => void;
+    /** The fan closed the modal. NOT a failure. */
+    onCancel?: () => void;
+    /** Fires once the checkout iframe has actually loaded. */
+    onLoad?: (response: unknown) => void;
+    onError?: (error: unknown) => void;
+  }
+
+  export default class PaystackPop {
+    /**
+     * Open the modal against an existing checkout session. The access code
+     * carries the session, so no public key is involved.
+     */
+    resumeTransaction(accessCode: string, options?: PaystackResumeOptions): unknown;
+    cancelTransaction(id?: string): void;
+  }
+}

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(),
       });
     };