@tribe-nest/forge 1.20.2 → 2.1.0

package/src/server/platform.ts

@@ -0,0 +1,208 @@
+/**
+ * Platform access for an app — the creator's BUSINESS data (memberships, orders,
+ * courses, contacts), as opposed to the app's own collections.
+ *
+ * SERVER ONLY. Never import this from a component or anything the browser
+ * bundles: it carries the app's platform credential.
+ *
+ * TWO LANES, AND THEY MUST NOT MERGE:
+ *  - Anything scoped to a PERSON ("my orders", "my membership") uses the signed-in
+ *    user's own token — the existing hooks. The platform checks that user's access.
+ *  - This client acts as the APP, with what the owner granted it. Use it for
+ *    business-level work and for reacting to events.
+ *
+ * NEVER answer an end-user request straight from this client. That is what turns
+ * "show me my membership" into "show me everyone's". Do your own authorization
+ * first, then use it for the part that genuinely needs owner-level access.
+ */
+
+export type PlatformConfig = {
+  /** The TribeNest public API base (VITE_API_URL). */
+  apiUrl: string;
+  /** The app's platform token, injected as a server-only Worker binding. */
+  token: string;
+};
+
+export type PlatformAction = {
+  id: string;
+  domain: string;
+  title: string;
+  description: string;
+  risk: "read" | "write" | "send" | "spend" | "destructive";
+};
+
+export class PlatformError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    /** Correlates with the platform's audit trail — log it when reporting a failure. */
+    readonly requestId?: string,
+  ) {
+    super(message);
+    this.name = "PlatformError";
+  }
+}
+
+/**
+ * A client for the platform actions this app has been granted.
+ *
+ * @example
+ * ```ts
+ * const platform = createPlatformClient({ apiUrl: env.API_URL, token: env.TN_APP_TOKEN })
+ * const { actions } = await platform.listActions()      // what this app may do
+ * await platform.run("blog.post.create", { title, content }, { idempotencyKey: myRecordId })
+ * ```
+ */
+export function createPlatformClient(config: PlatformConfig) {
+  const base = config.apiUrl.replace(/\/$/, "");
+
+  const request = async (path: string, init: RequestInit = {}) => {
+    const res = await fetch(`${base}/app-api${path}`, {
+      ...init,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${config.token}`,
+        ...(init.headers ?? {}),
+      },
+    });
+    const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+    if (!res.ok) {
+      // The message names the missing permission and how to ask for it — pass it
+      // through verbatim rather than flattening it to "request failed".
+      throw new PlatformError(
+        String(body.message ?? `Platform request failed (${res.status})`),
+        res.status,
+        body.requestId as string | undefined,
+      );
+    }
+    return body;
+  };
+
+  return {
+    /**
+     * What this app can actually do, already filtered to its grants.
+     *
+     * `missing` lists what was withheld and which permission would unlock it —
+     * useful in a log line when a feature silently does nothing.
+     */
+    async listActions(opts: { domain?: string; query?: string } = {}) {
+      const params = new URLSearchParams();
+      if (opts.domain) params.set("domain", opts.domain);
+      if (opts.query) params.set("query", opts.query);
+      const qs = params.toString();
+      return request(`/actions${qs ? `?${qs}` : ""}`) as Promise<{
+        actions: PlatformAction[];
+        missing: Array<{ id: string; reason: string; permission?: string }>;
+        requestId: string;
+      }>;
+    },
+
+    /** An action's input schema and a worked example. */
+    async describeAction(id: string) {
+      return request(`/actions/${encodeURIComponent(id)}`);
+    },
+
+    /**
+     * Run an action.
+     *
+     * `idempotencyKey` is REQUIRED for anything that writes. Derive it from your
+     * own record id: event delivery is at-least-once and jobs retry, so a write
+     * without one duplicates the first time anything is redelivered. A replay
+     * returns the original result instead of acting again.
+     */
+    async run<T = unknown>(
+      id: string,
+      input: unknown,
+      opts: { idempotencyKey?: string; dryRun?: boolean } = {},
+    ): Promise<T> {
+      const body = await request(`/actions/${encodeURIComponent(id)}`, {
+        method: "POST",
+        headers: opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {},
+        body: JSON.stringify({ input, ...(opts.dryRun ? { dryRun: true } : {}) }),
+      });
+      return body.result as T;
+    },
+
+    /**
+     * Validate a write without performing it. Worth doing before a mutation you
+     * cannot undo — it costs one call and catches a bad shape before it lands.
+     */
+    async dryRun(id: string, input: unknown) {
+      return request(`/actions/${encodeURIComponent(id)}`, {
+        method: "POST",
+        body: JSON.stringify({ input, dryRun: true }),
+      });
+    },
+  };
+}
+
+export type PlatformClient = ReturnType<typeof createPlatformClient>;
+
+// --------------------------------------------------------------------- events
+
+export type PlatformEvent<T = Record<string, unknown>> = {
+  event: string;
+  /** Dedupe on THIS. The same event arrives again on retry or replay. */
+  eventId: string;
+  appId: string;
+  profileId: string;
+  occurredAt: string;
+  data: T;
+};
+
+/**
+ * Verify and parse a platform event delivered to your app.
+ *
+ * Deliveries are signed; an unverified body is untrusted input from the open
+ * internet, so this throws rather than returning something that looks valid.
+ *
+ * DELIVERY IS AT-LEAST-ONCE. Record `eventId` and ignore one you have already
+ * processed — the same event WILL arrive twice after a retry or an owner replay,
+ * and a handler that acts twice will double-charge or double-send. That dedupe is
+ * also what makes the owner's 48-hour replay safe to use.
+ *
+ * @example
+ * ```ts
+ * const event = await verifyPlatformEvent(request, env.TN_EVENT_SECRET)
+ * if (await alreadyHandled(event.eventId)) return new Response("ok")
+ * await grantAccessFor(event.data)
+ * await markHandled(event.eventId)
+ * ```
+ */
+export async function verifyPlatformEvent<T = Record<string, unknown>>(
+  request: Request,
+  secret: string,
+): Promise<PlatformEvent<T>> {
+  const signature = request.headers.get("x-tribenest-signature");
+  if (!signature) throw new Error("Missing platform event signature.");
+
+  const body = await request.text();
+  const expected = await hmacHex(secret, body);
+  if (!timingSafeEqual(signature, expected)) {
+    throw new Error("Platform event signature did not verify.");
+  }
+  return JSON.parse(body) as PlatformEvent<T>;
+}
+
+async function hmacHex(secret: string, body: string): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
+  return Array.from(new Uint8Array(sig))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** Constant-time compare — a fast-exit compare leaks the signature a byte at a time. */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}

package/src/types/models.ts

@@ -307,6 +307,7 @@ export type CollectionFieldType =
   | "number"
   | "boolean"
   | "date"
+  | "datetime"
   | "select"
   | "multiselect"
   | "tags"
@@ -436,13 +437,36 @@ export type CollectionQuery = {
 
 /** Aggregation over a collection (group-by + metrics) — POST /aggregate. */
 export type CollectionAggregate = {
-  groupBy: string;
+  /**
+   * The dimension(s) to group by. Pass several to CROSS-TABULATE in one call —
+   * `["campaign", "product"]` returns a bucket per pair, instead of one request
+   * per campaign. A bare string means a single dimension.
+   */
+  groupBy: string | string[];
   metrics?: Array<{ op: "count" | "sum" | "avg" | "min" | "max"; field?: string; as: string }>;
   having?: Array<{ metric: string; op: "gt" | "gte" | "lt" | "lte" | "eq" | "ne"; value: number }>;
   orderBy?: { metric: string; dir?: "asc" | "desc" };
   limit?: number;
 };
-export type CollectionAggregateBucket = { value: string; count: number } & Record<string, number | string>;
+/**
+ * One group. Read `values` (every dimension, keyed by field) when grouping by
+ * more than one; `value` is the first dimension, kept for single-dimension code.
+ */
+export type CollectionAggregateBucket = {
+  value: string;
+  values: Record<string, string>;
+  count: number;
+} & Record<string, number | string | Record<string, string>>;
+
+/**
+ * An aggregate's outcome. `truncated` means the groups were CUT OFF at
+ * `limit` — check it before summing buckets into a total.
+ */
+export type CollectionAggregateResult = {
+  buckets: CollectionAggregateBucket[];
+  truncated: boolean;
+  limit: number;
+};
 
 export type MediaType = "image" | "video" | "audio" | "document";
 

package/src/ui/headless/checkout/useCheckout.ts

@@ -11,6 +11,7 @@ import {
   type ShippingCountry,
 } from "../../../data/queries/useShipping";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { useCreateCheckout, cartToCheckoutLines } from "../../../data/queries/useCheckouts";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 import { ProductDeliveryType, PaymentProviderName, type ApiError, type PublicTaxQuote } from "../../../types/models";
@@ -89,19 +90,34 @@ function messageOf(e: unknown): string | undefined {
 export function useCheckout(opts: UseCheckoutOptions = {}) {
   const finalisePath = opts.finalisePath ?? "/checkout/finalise";
   const { user } = usePublicAuth();
-  const { cartItems, isReady: isCartReady } = useCart();
+  const { cartItems, ticketItems, isBundle, isReady: isCartReady } = useCart();
   const { data: countries = [] } = useShippingCountries();
   const shippingRates = useShippingRates();
   const createOrder = useCreateOrder();
+  const createCheckout = useCreateCheckout();
   const applyCouponMutation = useApplyCoupon();
 
   const hasPhysicalProduct = useMemo(
     () => cartItems.some((item) => item.deliveryType === ProductDeliveryType.Physical),
     [cartItems],
   );
+  // Tickets count toward the total the buyer is shown and charged; a
+  // products-only cart is unchanged because `ticketItems` is then empty.
   const subTotal = useMemo(
-    () => round2(cartItems.reduce((sum, item) => sum + item.price * item.quantity, 0)),
-    [cartItems],
+    () =>
+      round2(
+        cartItems.reduce((sum, item) => sum + item.price * item.quantity, 0) +
+          ticketItems.reduce(
+            (sum, t) =>
+              sum +
+              Object.entries(t.tickets).reduce(
+                (acc, [id, qty]) => acc + (t.ticketMeta[id]?.price ?? 0) * qty,
+                0,
+              ),
+            0,
+          ),
+      ),
+    [cartItems, ticketItems],
   );
 
   const [currentStage, setCurrentStage] = useState<CheckoutStage>("userDetails");
@@ -135,6 +151,8 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
 
   const [isFreeCheckoutLoading, setIsFreeCheckoutLoading] = useState(false);
   const [created, setCreated] = useState<CreateOrderResult | null>(null);
+  /** Set instead of `created` when the cart is a bundle. */
+  const [checkoutId, setCheckoutId] = useState<string | null>(null);
   const [startError, setStartError] = useState("");
   const startedRef = useRef(false);
 
@@ -161,6 +179,28 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
   useEffect(() => {
     if (currentStage !== "payment" || !isPaidCheckout || startedRef.current) return;
     startedRef.current = true;
+
+    // A cart spanning tickets AND products goes through the bundle engine so
+    // both settle on one payment. Every single-surface cart keeps the flow it
+    // has always had, below.
+    if (isBundle) {
+      createCheckout
+        .mutateAsync({
+          firstName: guestUserData?.firstName || user?.firstName || "",
+          lastName: guestUserData?.lastName || user?.lastName || "",
+          email: guestUserData?.email || user?.email || "",
+          accountId: user?.id,
+          shippingAddress: shippingData,
+          selectedShippingRates: selectedShippingRates.length ? selectedShippingRates : undefined,
+          attributionRefId: readAttributionRef() ?? undefined,
+          ...(readLanding() ?? {}),
+          lines: cartToCheckoutLines(cartItems, ticketItems),
+        })
+        .then((r) => setCheckoutId(r.checkoutId))
+        .catch((e) => setStartError(messageOf(e) || "An error occurred"));
+      return;
+    }
+
     createOrder
       .mutateAsync({
         amount: subTotal,
@@ -183,14 +223,17 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [currentStage, isPaidCheckout]);
 
-  const returnUrl = created
-    ? `${typeof window !== "undefined" ? window.location.origin : ""}${finalisePath}?orderId=${created.orderId}`
-    : "";
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const returnUrl = checkoutId
+    ? `${origin}${finalisePath}?checkoutId=${checkoutId}`
+    : created
+      ? `${origin}${finalisePath}?orderId=${created.orderId}`
+      : "";
   const flow = usePaymentFlow({
-    path: "/public/orders/start-payment",
-    body: { orderId: created?.orderId },
+    path: checkoutId ? "/public/checkouts/start-payment" : "/public/orders/start-payment",
+    body: checkoutId ? { checkoutId } : { orderId: created?.orderId },
     returnUrl,
-    enabled: !!created?.orderId,
+    enabled: !!checkoutId || !!created?.orderId,
   });
 
   const orderId = created?.orderId ?? null;
@@ -394,6 +437,10 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     confirmRates,
     // ── Order + payment ────────────────────────────────────────────────────────
     orderId,
+    /** Set instead of `orderId` when the cart spans surfaces. */
+    checkoutId,
+    isBundle,
+    ticketItems,
     isCreatingOrder: createOrder.isPending || flow.isStarting,
     startError,
     provider,

package/src/ui/headless/event/useEventCheckout.ts

@@ -1,5 +1,6 @@
 import { useMemo, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useCart } from "../../../contexts/CartContext";
 import { useEvent, useCreateEventOrder } from "../../../data/queries/useEvents";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 import { readAttributionRef } from "../../../utils/attribution";
@@ -29,6 +30,7 @@ const errMessage = (e: unknown) =>
  */
 export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions = {}) {
   const { user } = usePublicAuth();
+  const { setTickets, hasTicketsFor } = useCart();
   // The detail is resolved by slug; the order is created against the real event
   // id (the orders endpoint looks the event up by id, not slug).
   const { data: event, isLoading } = useEvent(slug);
@@ -66,6 +68,37 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       return next;
     });
 
+  /**
+   * Put this selection in the cart instead of paying for it now — the exit
+   * that makes add-ons possible, because the buyer has to be able to leave for
+   * a product page and come back with the tickets still chosen.
+   *
+   * A tickets-only purchase still uses `continueToPayment`, the original
+   * untouched flow; the cart path only matters once something else is in the
+   * cart too.
+   */
+  const addTicketsToCart = () => {
+    if (ticketCount === 0) {
+      setError("Select at least one ticket.");
+      return false;
+    }
+    if (!event) return false;
+    setError(null);
+    setTickets({
+      eventId: event.id,
+      eventSlug: slug ?? event.id,
+      eventTitle: event.title,
+      coverImage: event.media?.find((m: { type: string }) => m.type === "image")?.url,
+      tickets: { ...selectedTickets },
+      ticketMeta: Object.fromEntries(
+        event.tickets
+          .filter((t) => (selectedTickets[t.id] ?? 0) > 0)
+          .map((t) => [t.id, { title: t.title, price: t.price }]),
+      ),
+    });
+    return true;
+  };
+
   const goToDetails = () => {
     if (ticketCount === 0) {
       setError("Select at least one ticket.");
@@ -132,6 +165,9 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     questionnaire,
     setQuestionnaire,
     goToDetails,
+    addTicketsToCart,
+    /** True when this event's tickets are already sitting in the cart. */
+    ticketsInCart: event ? hasTicketsFor(event.id) : false,
     continueToPayment,
     clientSecret: flow.clientSecret,
     returnUrl,

package/src/ui/headless/funnel/Funnel.tsx

@@ -0,0 +1,159 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, type ReactNode } from "react";
+import { useTrackEvent } from "../../../data/queries/useAnalytics";
+import { useCookieConsent } from "../consent/useCookieConsent";
+import { getFunnelSessionId, markOnce, resetFunnelSession } from "./funnelSession";
+
+/** Event types this primitive writes to the first-party analytics feed. */
+export const FUNNEL_EVENTS = {
+  entered: "funnel_entered",
+  stepViewed: "funnel_step_viewed",
+  stepCompleted: "funnel_step_completed",
+  converted: "funnel_converted",
+} as const;
+
+export interface FunnelContextValue {
+  funnelId: string;
+  funnelName?: string;
+  /** The declared step ids, in order. */
+  steps: string[];
+  /** This visitor's id for this funnel, or null when storage is unavailable. */
+  funnelSessionId: string | null;
+  /** Position of a step in the declared order, or -1 if it wasn't declared. */
+  indexOf(stepId: string): number;
+  /** Record that a step became visible. De-duplicated per funnel session. */
+  viewStep(stepId: string, data?: Record<string, unknown>): void;
+  /** Record that a step's goal was met (form submitted, CTA taken, payment made). */
+  completeStep(stepId: string, data?: Record<string, unknown>): void;
+  /** Terminal success for the whole funnel. */
+  convert(data?: Record<string, unknown>): void;
+  /** Start a fresh session for this funnel (a deliberate "start over"). */
+  restart(): void;
+}
+
+const FunnelContext = createContext<FunnelContextValue | null>(null);
+
+export interface FunnelProps {
+  /** Stable id — the grouping key in the admin report. Changing it starts a new funnel. */
+  id: string;
+  /**
+   * The ordered step ids.
+   *
+   * Required, and the reason this component exists rather than a bare `track()`
+   * call: a step nobody reaches emits nothing, so a report built only from
+   * observed events would end the funnel at the last step someone got to and
+   * quietly hide the rest. The declaration ships with the entry event, and the
+   * report joins counts onto it — so an untouched step shows as 0, which is the
+   * number you actually needed to see.
+   */
+  steps: string[];
+  /** Human label for the report. Defaults to the id. */
+  name?: string;
+  /** Master switch — pass `false` in previews/editors to record nothing. Default `true`. */
+  enabled?: boolean;
+  /**
+   * Honour the visitor's cookie choice, matching `<ForgeAnalytics />`. Default
+   * `true`: nothing is recorded until `performance` consent is given.
+   */
+  requireConsent?: boolean;
+  children: ReactNode;
+}
+
+/**
+ * Wraps a multi-step flow and records how far each visitor gets.
+ *
+ * It renders nothing of its own — it supplies the context `useFunnelStep()`
+ * reads, and emits one `funnel_entered` event per visitor per funnel carrying
+ * the step declaration. Everything rides the existing first-party analytics
+ * feed (`POST /public/websites/track-event`), so funnels need no separate
+ * pipeline and travel with `website_events` when analytics moves to ClickHouse.
+ *
+ * Mount it above the steps. When each step is its own page, mount it in the
+ * layout those pages share — the session lives in `sessionStorage`, so it
+ * survives the navigations between them.
+ *
+ *     <Funnel id="spring-launch" steps={["landing", "quiz", "offer", "checkout"]}>
+ *       <Outlet />
+ *     </Funnel>
+ *
+ * Each step component then declares itself with one hook call:
+ *
+ *     const step = useFunnelStep("optin");
+ */
+export function Funnel({ id, steps, name, enabled = true, requireConsent = true, children }: FunnelProps) {
+  const { performance: perfConsent } = useCookieConsent();
+  const on = enabled && (!requireConsent || perfConsent);
+  const { track } = useTrackEvent();
+
+  // Read once per render pass rather than per event: minting is idempotent, but
+  // touching storage on every call for no reason isn't free.
+  const funnelSessionId = useMemo(() => (on ? getFunnelSessionId(id) : null), [on, id]);
+
+  // `steps` is almost always an inline array literal, so identity changes every
+  // render. Compare by value or the entry effect re-fires forever. Joined on a
+  // character a step id can't contain, so ["a b"] and ["a","b"] can't collide
+  // into the same key.
+  const stepsKey = steps.join("\u0000");
+  const stepList = useMemo(() => steps.slice(), [stepsKey]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const emit = useCallback(
+    (eventType: string, data: Record<string, unknown>) => {
+      if (!on) return;
+      track(eventType, {
+        funnelId: id,
+        funnelName: name ?? id,
+        funnelSessionId: funnelSessionId ?? undefined,
+        pathname: typeof window !== "undefined" ? window.location.pathname : undefined,
+        ...data,
+      });
+    },
+    [on, track, id, name, funnelSessionId],
+  );
+
+  // Keep the latest emitter without making the entry effect depend on it — the
+  // entry event must fire once per session, not once per identity change.
+  const emitRef = useRef(emit);
+  emitRef.current = emit;
+
+  useEffect(() => {
+    if (!on) return;
+    if (!markOnce(id, "entered")) return;
+    emitRef.current(FUNNEL_EVENTS.entered, { steps: stepList, stepCount: stepList.length });
+  }, [on, id, stepsKey]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const value = useMemo<FunnelContextValue>(() => {
+    const indexOf = (stepId: string) => stepList.indexOf(stepId);
+    return {
+      funnelId: id,
+      funnelName: name,
+      steps: stepList,
+      funnelSessionId,
+      indexOf,
+      viewStep: (stepId, data) => {
+        // One view per step per session: back-navigation and remounts are not
+        // new visitors. Counts are DISTINCT-session anyway, so this is about
+        // keeping the event feed honest rather than correcting the numbers.
+        if (!markOnce(id, `view_${stepId}`)) return;
+        emit(FUNNEL_EVENTS.stepViewed, { stepId, stepIndex: indexOf(stepId), ...data });
+      },
+      completeStep: (stepId, data) => {
+        if (!markOnce(id, `complete_${stepId}`)) return;
+        emit(FUNNEL_EVENTS.stepCompleted, { stepId, stepIndex: indexOf(stepId), ...data });
+      },
+      convert: (data) => {
+        if (!markOnce(id, "converted")) return;
+        emit(FUNNEL_EVENTS.converted, { ...data });
+      },
+      restart: () => resetFunnelSession(id),
+    };
+  }, [id, name, stepList, funnelSessionId, emit]);
+
+  return <FunnelContext.Provider value={value}>{children}</FunnelContext.Provider>;
+}
+
+/**
+ * The surrounding funnel, or `null` outside one. Null rather than throwing so a
+ * page can be dropped into a funnel or used standalone without branching.
+ */
+export function useFunnel(): FunnelContextValue | null {
+  return useContext(FunnelContext);
+}