@tribe-nest/forge 2.2.0 → 3.4.0

package/src/ui/headless/calendar/useAddToCalendar.ts

@@ -0,0 +1,194 @@
+import { useMemo } from "react";
+
+/**
+ * "Add to calendar" link building — the whole of it. Styled components render
+ * anchors; they never assemble a URL themselves, so a fix to (say) Google's
+ * `dates` format lands in exactly one place.
+ *
+ * Everything here is framework-free and dependency-free: Forge ships no date
+ * library, so the two formats the providers want are derived from the platform
+ * `Date` alone.
+ */
+
+export type AddToCalendarInput = {
+  /** Event/session name — becomes the calendar entry's title. */
+  title: string;
+  /** Absolute instant the thing starts (ISO-8601 with an offset or `Z`). */
+  start: string | Date;
+  /** Absolute instant it ends. Nullable — falls back to `start + defaultDurationMinutes`. */
+  end?: string | Date | null;
+  /** Fallback length when `end` is absent. Defaults to 120 minutes. */
+  defaultDurationMinutes?: number;
+  /** Long description. HTML is stripped and truncated before it goes in a URL. */
+  description?: string | null;
+  /** Human-readable place (a street address, or "Virtual"). */
+  location?: string | null;
+  /** Canonical page for the event; appended to the description body when present. */
+  url?: string | null;
+  /**
+   * Absolute URL to a downloadable `.ics` (what Apple Calendar / Outlook desktop
+   * want). Forge does not synthesize this — the host passes the endpoint it has.
+   * When absent, `ics` comes back `null` and no Apple option is offered.
+   */
+  icsUrl?: string | null;
+};
+
+export type AddToCalendarLinks = {
+  /** Google Calendar "TEMPLATE" prefill. */
+  google: string;
+  /** Outlook.com (personal accounts). */
+  outlook: string;
+  /** Outlook on the web for work/school accounts (Microsoft 365). */
+  office365: string;
+  /** Yahoo Calendar. */
+  yahoo: string;
+  /** Pass-through of `icsUrl` — the Apple/desktop route. `null` when not supplied. */
+  ics: string | null;
+  startsAt: Date;
+  endsAt: Date;
+};
+
+/** Length of a calendar entry when the caller has no end time. */
+const DEFAULT_DURATION_MINUTES = 120;
+
+/** Calendar providers put the description in a URL; keep it well under limits. */
+const MAX_DESCRIPTION_CHARS = 800;
+
+/** Parse anything the caller has to a valid `Date`, or `null` if it isn't one. */
+function toDate(value: string | Date | null | undefined): Date | null {
+  if (value === null || value === undefined || value === "") return null;
+  const d = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * UTC "basic format" (RFC 5545 / what Google and Yahoo want):
+ * `2026-03-15T06:30:00.000Z` → `20260315T063000Z`.
+ */
+export function toUtcBasic(d: Date): string {
+  return d.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+}
+
+/**
+ * Flatten an HTML description to plain text. Event/session descriptions in this
+ * codebase are rich text rendered with `dangerouslySetInnerHTML`, so the raw
+ * value is markup — pasting it into a calendar body would show tags.
+ *
+ * `&` is decoded LAST so an encoded entity (`<`) doesn't turn into a
+ * live one.
+ */
+export function stripHtml(html: string, maxLength: number = MAX_DESCRIPTION_CHARS): string {
+  const text = html
+    .replace(/<\s*br\s*\/?\s*>/gi, "\n")
+    .replace(/<\s*\/\s*(p|div|li|tr|h[1-6])\s*>/gi, "\n")
+    .replace(/<[^>]*>/g, "")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&#39;/g, "'")
+    .replace(/&quot;/gi, '"')
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&amp;/gi, "&")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+
+  return text.length > maxLength ? `${text.slice(0, maxLength - 1).trimEnd()}…` : text;
+}
+
+const enc = encodeURIComponent;
+
+/**
+ * Build every provider URL for one calendar entry. Returns `null` when the
+ * start is missing or unparseable — callers render nothing rather than a link
+ * that would prefill garbage.
+ */
+export function buildAddToCalendarLinks(input: AddToCalendarInput): AddToCalendarLinks | null {
+  const startsAt = toDate(input.start);
+  if (!startsAt) return null;
+
+  const durationMinutes =
+    input.defaultDurationMinutes && input.defaultDurationMinutes > 0
+      ? input.defaultDurationMinutes
+      : DEFAULT_DURATION_MINUTES;
+
+  const parsedEnd = toDate(input.end);
+  // An end at-or-before the start is as useless as no end at all.
+  const endsAt =
+    parsedEnd && parsedEnd.getTime() > startsAt.getTime()
+      ? parsedEnd
+      : new Date(startsAt.getTime() + durationMinutes * 60_000);
+
+  const title = (input.title || "").trim();
+  const location = (input.location || "").trim();
+
+  const body = [input.description ? stripHtml(input.description) : "", (input.url || "").trim()]
+    .filter(Boolean)
+    .join("\n\n");
+
+  const startBasic = toUtcBasic(startsAt);
+  const endBasic = toUtcBasic(endsAt);
+  const startIso = startsAt.toISOString();
+  const endIso = endsAt.toISOString();
+
+  const outlookQuery =
+    `path=${enc("/calendar/action/compose")}` +
+    `&rru=addevent` +
+    `&subject=${enc(title)}` +
+    `&startdt=${enc(startIso)}` +
+    `&enddt=${enc(endIso)}` +
+    `&body=${enc(body)}` +
+    `&location=${enc(location)}`;
+
+  return {
+    google:
+      `https://calendar.google.com/calendar/render?action=TEMPLATE` +
+      `&text=${enc(title)}` +
+      `&dates=${startBasic}/${endBasic}` +
+      `&details=${enc(body)}` +
+      `&location=${enc(location)}`,
+    outlook: `https://outlook.live.com/calendar/0/deeplink/compose?${outlookQuery}`,
+    office365: `https://outlook.office.com/calendar/0/deeplink/compose?${outlookQuery}`,
+    yahoo:
+      `https://calendar.yahoo.com/?v=60` +
+      `&title=${enc(title)}` +
+      `&st=${startBasic}` +
+      `&et=${endBasic}` +
+      `&desc=${enc(body)}` +
+      `&in_loc=${enc(location)}`,
+    ics: input.icsUrl || null,
+    startsAt,
+    endsAt,
+  };
+}
+
+/**
+ * React wrapper over {@link buildAddToCalendarLinks}. Memoized on the primitive
+ * inputs so an anchor's `href` is referentially stable between renders.
+ *
+ * Returns `null` for an unusable start time — safe to call unconditionally with
+ * data that may still be loading.
+ */
+export function useAddToCalendar(input: AddToCalendarInput | null | undefined): AddToCalendarLinks | null {
+  const title = input?.title;
+  const start = input?.start;
+  const end = input?.end;
+  const defaultDurationMinutes = input?.defaultDurationMinutes;
+  const description = input?.description;
+  const location = input?.location;
+  const url = input?.url;
+  const icsUrl = input?.icsUrl;
+
+  return useMemo(() => {
+    if (!start) return null;
+    return buildAddToCalendarLinks({
+      title: title ?? "",
+      start,
+      end,
+      defaultDurationMinutes,
+      description,
+      location,
+      url,
+      icsUrl,
+    });
+  }, [title, start, end, defaultDurationMinutes, description, location, url, icsUrl]);
+}

package/src/ui/headless/checkout/_tests/bundleCoupon.spec.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from "vitest";
+import { bundleCouponSummary, bundleCouponRequestBody, bundleReturnUrl } from "../bundleCoupon";
+import type { ApplyCheckoutCouponResult } from "../../../../data/queries/useCheckouts";
+
+/**
+ * A bundle's discount code, as `useCheckout` handles it.
+ *
+ * These are the two decisions that used to be impossible to make at all: before
+ * `/public/checkouts/apply-coupon` existed, a bundle's code was consumed by the
+ * call that CREATED the checkout, so for a signed-in buyer with a digital-only
+ * cart — who enters the payment stage on mount — the field froze before it could
+ * be typed into.
+ *
+ * They live outside the hook so they can be asserted without a provider tree,
+ * the same reason `couponFailureMessage` does.
+ */
+
+/** The endpoint's answer, defaulted to "APPLYME20 took $2 off a $60 bundle". */
+const answer = (overrides: Partial<ApplyCheckoutCouponResult> = {}): ApplyCheckoutCouponResult => ({
+  checkoutId: "checkout-1",
+  currency: "USD",
+  subtotalCents: 6000,
+  discountCents: 200,
+  couponId: "coupon-1",
+  totalCents: 5800,
+  appliedCoupons: [{ code: "APPLYME20", discountKind: "simple", discountAmount: 2 }],
+  paymentSecret: "pi_2_secret",
+  paymentId: "pi_2",
+  chargedAmount: 58,
+  chargedCurrency: "USD",
+  isFreeCheckout: false,
+  ...overrides,
+});
+
+describe("bundleCouponSummary — applying", () => {
+  it("converts the minor-unit discount and names the coupon", () => {
+    const next = bundleCouponSummary(answer());
+
+    expect(next.discountAmount).toBe(2);
+    expect(next.appliedCoupon).toEqual({ code: "APPLYME20", discountAmount: 2 });
+    expect(next.settledCheckoutId).toBeNull();
+  });
+
+  it("labels an AUTOMATIC discount the buyer never typed", () => {
+    // The whole point of the response carrying `appliedCoupons`: without it a
+    // no-code discount could only be drawn as an unexplained amount, because
+    // there is no public `couponId` → code lookup.
+    const next = bundleCouponSummary(
+      answer({ appliedCoupons: [{ code: "SUMMER10", discountKind: "simple", discountAmount: 6 }], discountCents: 600 }),
+    );
+
+    expect(next.appliedCoupon).toEqual({ code: "SUMMER10", discountAmount: 6 });
+  });
+
+  it("moves the payment element onto the re-minted intent", () => {
+    // Applying re-prices AND re-mints. Leaving the old secret in place would
+    // have the buyer confirm a payment quoting the PRE-coupon amount.
+    const next = bundleCouponSummary(answer());
+
+    expect(next.paymentUpdate).toEqual({
+      paymentSecret: "pi_2_secret",
+      paymentId: "pi_2",
+      chargedAmount: 58,
+      chargedCurrency: "USD",
+    });
+    expect(next.chargedTotal).toEqual({ amount: 58, currency: "USD" });
+  });
+
+  it("claims no payment when the bundle had no intent to replace", () => {
+    // A bundle that has not reached start-payment yet: the client's own
+    // start-payment will pick the new figure up, so nothing may supersede it.
+    const next = bundleCouponSummary(answer({ paymentSecret: "", paymentId: "", chargedAmount: 0, chargedCurrency: "" }));
+
+    expect(next.paymentUpdate).toBeNull();
+    expect(next.chargedTotal).toBeNull();
+    // The discount is still real and still shown.
+    expect(next.discountAmount).toBe(2);
+    expect(next.appliedCoupon).toEqual({ code: "APPLYME20", discountAmount: 2 });
+  });
+
+  it("does not claim a coupon it cannot name", () => {
+    // A reduction with no coupon behind it is reported as an amount and nothing
+    // more — inventing a label is how a buyer ends up chasing a code that
+    // does not exist.
+    const next = bundleCouponSummary(answer({ appliedCoupons: [] }));
+
+    expect(next.discountAmount).toBe(2);
+    expect(next.appliedCoupon).toBeNull();
+  });
+});
+
+describe("bundleCouponSummary — removing", () => {
+  it("restores the undiscounted figure and drops the applied coupon", () => {
+    const next = bundleCouponSummary(
+      answer({
+        discountCents: 0,
+        couponId: null,
+        totalCents: 6000,
+        appliedCoupons: [],
+        paymentSecret: "pi_3_secret",
+        paymentId: "pi_3",
+        chargedAmount: 60,
+      }),
+    );
+
+    expect(next.discountAmount).toBe(0);
+    expect(next.appliedCoupon).toBeNull();
+    // The full price is what the buyer is now charged, on a fresh intent.
+    expect(next.chargedTotal).toEqual({ amount: 60, currency: "USD" });
+    expect(next.paymentUpdate?.paymentId).toBe("pi_3");
+    expect(next.settledCheckoutId).toBeNull();
+  });
+});
+
+describe("bundleCouponSummary — a bundle taken to zero", () => {
+  it("reports the settled checkout so the buyer is sent to finalise", () => {
+    // There is no intent to confirm: the server settled and fulfilled it. Left
+    // unhandled, the buyer waits in front of a payment form that will never be
+    // asked to do anything.
+    const next = bundleCouponSummary(
+      answer({
+        discountCents: 6000,
+        totalCents: 0,
+        appliedCoupons: [{ code: "ALLOFIT", discountKind: "simple", discountAmount: 60 }],
+        paymentSecret: "",
+        paymentId: "",
+        chargedAmount: 0,
+        chargedCurrency: "",
+        isFreeCheckout: true,
+      }),
+    );
+
+    expect(next.settledCheckoutId).toBe("checkout-1");
+    expect(next.paymentUpdate).toBeNull();
+    expect(next.chargedTotal).toBeNull();
+    expect(next.discountAmount).toBe(60);
+    expect(next.appliedCoupon).toEqual({ code: "ALLOFIT", discountAmount: 60 });
+  });
+});
+
+describe("bundleCouponRequestBody", () => {
+  const base = { profileId: "p1", checkoutId: "c1", returnUrl: "https://x.test/finalise?checkoutId=c1" };
+
+  it("sends the trimmed code when applying", () => {
+    expect(bundleCouponRequestBody({ ...base, couponCode: "  applyme20 " })).toEqual({
+      ...base,
+      couponCode: "applyme20",
+    });
+  });
+
+  it("omits the field entirely when removing", () => {
+    // The endpoint validates `couponCode` as `min(1)`, so an empty string is a
+    // 400 — "take my code off" would fail and the discount would stay on.
+    expect(bundleCouponRequestBody(base)).toEqual(base);
+    expect(bundleCouponRequestBody({ ...base, couponCode: "" })).toEqual(base);
+    expect(bundleCouponRequestBody({ ...base, couponCode: "   " })).toEqual(base);
+    expect("couponCode" in bundleCouponRequestBody(base)).toBe(false);
+  });
+});
+
+describe("bundleReturnUrl", () => {
+  it("returns the buyer to the bundle's own finalise page", () => {
+    // `?checkoutId=` and not `?orderId=`: the finalise page resolves a bundle
+    // through the checkout, and a bundle's children are several orders.
+    expect(bundleReturnUrl("https://artist.test", "/checkout/finalise", "c1")).toBe(
+      "https://artist.test/checkout/finalise?checkoutId=c1",
+    );
+  });
+});

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

@@ -0,0 +1,96 @@
+import type { ApplyCheckoutCouponResult, AppliedBundleCoupon } from "../../../data/queries/useCheckouts";
+
+/**
+ * The two decisions a bundle's discount code turns on, kept out of the hook so
+ * they can be asserted without a provider tree.
+ *
+ * Both exist because a bundle is the odd one out: it is the only checkout that
+ * answers in MINOR units, the only one whose "remove" is expressed by the
+ * ABSENCE of a field rather than an empty one, and the only one that can settle
+ * itself — a code that takes it to zero leaves nothing to pay for.
+ */
+
+/** What the summary and the payment element read after an apply or a remove. */
+export type BundleCouponSummary = {
+  /** MAJOR units, converted from the endpoint's minor-unit answer. */
+  discountAmount: number;
+  /**
+   * The discount as the buyer sees it, or null when nothing came off.
+   *
+   * Named from the server's `appliedCoupons`, so an AUTOMATIC discount the buyer
+   * never typed is labelled with its real code instead of appearing as an
+   * unexplained reduction.
+   */
+  appliedCoupon: { code: string; discountAmount: number } | null;
+  /**
+   * The re-minted intent. Applying re-prices AND re-mints, so the payment
+   * element must move onto this secret — the previous one still quotes the
+   * pre-coupon amount. Null when there was no intent to replace (the bundle had
+   * not started payment) or when the bundle settled for free.
+   */
+  paymentUpdate: {
+    paymentSecret: string;
+    paymentId: string;
+    chargedAmount: number;
+    chargedCurrency: string;
+  } | null;
+  /** The charged total for the summary, or null when there is nothing to charge. */
+  chargedTotal: { amount: number; currency: string } | null;
+  /**
+   * Set when the re-price took the bundle to zero. The server has already
+   * settled and fulfilled it, so the buyer belongs on the finalise page rather
+   * than in front of a payment form that will never be asked to do anything.
+   */
+  settledCheckoutId: string | null;
+};
+
+export function bundleCouponSummary(data: ApplyCheckoutCouponResult): BundleCouponSummary {
+  const discountAmount = (data.discountCents ?? 0) / 100;
+  const named: AppliedBundleCoupon | undefined = data.appliedCoupons?.[0];
+
+  return {
+    discountAmount,
+    // A discount with no coupon behind it cannot be labelled honestly, so it is
+    // not claimed as one — `discountAmount` still reports the reduction.
+    appliedCoupon: discountAmount > 0 && named ? { code: named.code, discountAmount } : null,
+    paymentUpdate:
+      data.paymentSecret && data.paymentId
+        ? {
+            paymentSecret: data.paymentSecret,
+            paymentId: data.paymentId,
+            chargedAmount: data.chargedAmount,
+            chargedCurrency: data.chargedCurrency,
+          }
+        : null,
+    chargedTotal: data.chargedAmount > 0 ? { amount: data.chargedAmount, currency: data.chargedCurrency } : null,
+    settledCheckoutId: data.isFreeCheckout ? data.checkoutId : null,
+  };
+}
+
+/**
+ * The body for `POST /public/checkouts/apply-coupon`.
+ *
+ * Removing sends NO `couponCode` at all. An empty string is a validation error
+ * on that endpoint (`min(1)`), so sending one would turn "take my code off" into
+ * a 400 and leave the discount in place.
+ */
+export function bundleCouponRequestBody(input: {
+  /** Optional only because `useForge()` types it so before the provider resolves. */
+  profileId?: string;
+  checkoutId: string;
+  returnUrl: string;
+  couponCode?: string;
+}): Record<string, unknown> {
+  const code = input.couponCode?.trim();
+  return {
+    profileId: input.profileId,
+    checkoutId: input.checkoutId,
+    returnUrl: input.returnUrl,
+    ...(code ? { couponCode: code } : {}),
+  };
+}
+
+/** The return URL a bundle's re-minted intent comes back to. */
+export function bundleReturnUrl(origin: string, finalisePath: string, checkoutId: string): string {
+  return `${origin}${finalisePath}?checkoutId=${checkoutId}`;
+}