@tribe-nest/forge 2.2.0 → 3.4.0

package/src/server/platformEvents.generated.ts

@@ -0,0 +1,422 @@
+// GENERATED FILE — DO NOT EDIT.
+// Produced from the platform event catalog by:
+//   cd apps/backend && npm run generate:forge-events
+//
+// The catalog (apps/backend/src/services/admin/app/eventCatalog.ts) is the single
+// definition of what an app can receive and what shape it arrives in. Editing
+// this file by hand creates a second one, and the copy that drifts is the one
+// nobody is testing.
+
+/**
+ * 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
+ * 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
+ * not build the full payload (the record was missing, or the enriched body did
+ * not match its own schema) and sent the identifying ids instead. Re-read what
+ * you need through the platform client rather than trusting the missing fields.
+ */
+export type PlatformEventMap = {
+  /**
+   * Affiliate applied — Someone applied to the affiliate program.
+   *
+   * Requires the `affiliates.read` grant.
+   */
+  "affiliate.applied": {
+    affiliateId: string;
+  };
+  /**
+   * Checkout abandoned — Someone started a checkout and did not finish it.
+   *
+   * Requires the `products.read` grant.
+   */
+  "checkout.abandoned": {
+    checkoutId: string;
+    source: string;
+    sourceRecordId?: string | null;
+    contactId?: string | null;
+    email?: string | null;
+    totalCents?: number | null;
+    currency?: string | null;
+  };
+  /**
+   * Checkout recovered — An abandoned checkout was completed after all.
+   *
+   * Requires the `products.read` grant.
+   */
+  "checkout.recovered": {
+    checkoutId: string;
+    source: string | null;
+    sourceRecordId: string | null;
+    contactId: string | null;
+    email: string | null;
+    totalCents: number | null;
+    currency: string | null;
+  };
+  /**
+   * Collection entry submitted — A visitor submitted an entry to a collection.
+   *
+   * Requires the `collections.read` grant.
+   */
+  "collection.submission": {
+    entryId: string;
+    collectionId: string;
+    collectionName?: string | null;
+    status?: string | null;
+  };
+  /**
+   * Community post created — A member posted in a community space.
+   *
+   * Requires the `community.new_post` grant.
+   */
+  "community_post.created": {
+    postId: string;
+    spaceId: string;
+    authorAccountId?: string | null;
+  };
+  /**
+   * Community reply created — A member replied to a community post.
+   *
+   * Requires the `community.new_comment` grant.
+   */
+  "community_reply.created": {
+    replyId: string;
+    postId: string;
+    spaceId?: string | null;
+    authorAccountId?: string | null;
+    parentReplyId?: string | null;
+  };
+  /**
+   * Contact form message — Someone sent a message through a website contact form.
+   *
+   * Requires the `contacts.read` grant.
+   */
+  "contact_message.created": {
+    senderName?: string | null;
+    senderEmail?: string | null;
+    message?: string | null;
+  };
+  /**
+   * Form submitted — A form was submitted. Carries the submission id — read the answers through the platform client.
+   *
+   * Requires the `forms.read` grant.
+   */
+  "contact.form_submitted": {
+    formId: string;
+    formTitle: string | null;
+    submissionId: string | null;
+    contactId: string | null;
+  };
+  /**
+   * Quiz completed — A contact completed a graded form, with their score and outcome.
+   *
+   * Requires the `contacts.read` grant.
+   */
+  "contact.quiz_completed": {
+    contactId: string | null;
+    formId: string;
+    submissionId?: string | null;
+    quizResultId?: string | null;
+    percent?: number | null;
+    passed?: boolean | null;
+    outcomeKey?: string | null;
+  };
+  /**
+   * Tag added to contact — A tag was applied to a contact.
+   *
+   * Requires the `contacts.read` grant.
+   */
+  "contact.tag_added": {
+    contactId: string;
+    tagId: string;
+  };
+  /**
+   * Course completed — A learner finished a course.
+   *
+   * Requires the `courses.read` grant.
+   */
+  "course.completed": {
+    courseId: string;
+    courseTitle: string | null;
+    courseAccessId: string | null;
+    contactId: string | null;
+    completedAt: string | null;
+  };
+  /**
+   * Lesson progressed — A learner completed a lesson.
+   *
+   * Requires the `courses.read` grant.
+   */
+  "course.lesson_progressed": {
+    courseId: string;
+    courseAccessId?: string | null;
+    lessonId?: string | null;
+    contactId?: string | null;
+    cohortId?: string | null;
+  };
+  /**
+   * Payment disputed — A customer disputed a payment (chargeback).
+   *
+   * Requires the `income.read` grant.
+   */
+  "dispute.created": {
+    disputeId: string;
+    amountCents?: number | null;
+    reason?: string | null;
+  };
+  /**
+   * Document signed or decided — A proposal or contract was signed, accepted or declined.
+   *
+   * Requires the `deals.read` grant.
+   */
+  "document.completed": {
+    documentId: string;
+    event: string;
+    title?: string | null;
+    kind?: string | null;
+  };
+  /**
+   * Email link clicked — A recipient clicked a link in a marketing email.
+   *
+   * Requires the `emails.read` grant.
+   */
+  "email.clicked": {
+    emailId: string;
+    contactId?: string | null;
+    linkUrl?: string | null;
+    occurredAt?: string | null;
+  };
+  /**
+   * Email opened — A recipient opened a marketing email.
+   *
+   * Requires the `emails.read` grant.
+   */
+  "email.opened": {
+    emailId: string;
+    contactId?: string | null;
+    occurredAt?: string | null;
+  };
+  /**
+   * Event tickets bought — Someone paid for tickets to an event.
+   *
+   * Requires the `events.read` grant.
+   */
+  "event_ticket_order.paid": {
+    orderId: string;
+    eventId: string | null;
+    status: string | null;
+    total: number | null;
+    currency: string | null;
+    buyer: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+    tickets: Array<{
+      ticketId: string | null;
+      quantity: number;
+      unitPrice: number | null;
+    }>;
+  };
+  /**
+   * Membership tier archived — A membership tier was archived and can no longer be joined.
+   *
+   * Requires the `membership.tier_archived` grant.
+   */
+  "membership_tier.archived": {
+    membershipTierId: string;
+    name: string | null;
+    archived: boolean;
+  };
+  /**
+   * Membership tier created — A new membership tier was published.
+   *
+   * Requires the `membership.tier_created` grant.
+   */
+  "membership_tier.created": {
+    membershipTierId: string;
+    name: string | null;
+    priceMonthly: number | null;
+    priceYearly: number | null;
+    isDefault: boolean;
+    archived: boolean;
+  };
+  /**
+   * Inbound message — An SMS or WhatsApp message arrived from a contact.
+   *
+   * Requires the `contacts.read` grant.
+   */
+  "message.received": {
+    channel: string;
+    inboundId: string;
+    contactId?: string | null;
+    fromPhone?: string | null;
+    body?: string | null;
+    occurredAt?: string | null;
+  };
+  /**
+   * Content reported — A member reported community content for moderation.
+   *
+   * Requires the `community.content_reported` grant.
+   */
+  "moderation.report_created": {
+    reportId: string;
+    entityId?: string | null;
+    entityType?: string | null;
+  };
+  /**
+   * Order paid — A store order was paid for. Carries the order, its line items and a buyer reference.
+   *
+   * Requires the `products.read` grant.
+   */
+  "order.paid": {
+    orderId: string;
+    status: string | null;
+    total: number | null;
+    currency: string | null;
+    placedAt: string | null;
+    buyer: {
+      contactId: string | null;
+      email: string | null;
+      name: string | null;
+    };
+    items: Array<{
+      productId: string | null;
+      variantId: string | null;
+      title: string | null;
+      quantity: number;
+      unitPrice: number | null;
+    }>;
+  };
+  /**
+   * Payout settled — A payout to the creator's bank account settled.
+   *
+   * Requires the `income.read` grant.
+   */
+  "payout.settled": {
+    payoutId: string | null;
+    status: string;
+    amountCents: number;
+    currency: string;
+  };
+  /**
+   * Member post published — A post was published to the member feed, with the tiers that can see it.
+   *
+   * Requires the `membership.new_post` grant.
+   */
+  "post.created": {
+    postId: string;
+    membershipTiers?: Array<unknown> | null;
+  };
+  /**
+   * Refund failed — A refund could not be completed.
+   *
+   * Requires the `income.read` grant.
+   */
+  "refund.failed": {
+    refundId: string;
+    amountCents: number;
+    currency?: string | null;
+    reason?: string | null;
+    sourceType?: string | null;
+    sourceId?: string | null;
+  };
+  /**
+   * Refund succeeded — A refund completed.
+   *
+   * Requires the `income.read` grant.
+   */
+  "refund.succeeded": {
+    refundId: string;
+    sourceType?: string | null;
+    sourceId?: string | null;
+    amountCents: number;
+    capturedCents?: number | null;
+  };
+  /**
+   * Review submitted — A customer left a review, with its rating and moderation status.
+   *
+   * Requires the `reviews.read` grant.
+   */
+  "review_submitted": {
+    reviewId: string;
+    entityType: string;
+    entityId: string;
+    contactId?: string | null;
+    rating?: number | null;
+    status?: string | null;
+    isEdit?: boolean | null;
+  };
+  /**
+   * Review published — A review passed moderation and is now public.
+   *
+   * Requires the `reviews.read` grant.
+   */
+  "review.published": {
+    reviewId: string;
+  };
+  /**
+   * Shipment status changed — A shipment for an order moved — dispatched, in transit, delivered.
+   *
+   * Requires the `products.read` grant.
+   */
+  "shipping.status_updated": {
+    orderId: string;
+    deliveryGroupId?: string | null;
+    shippingLabelId?: string | null;
+    status?: string | null;
+    trackingNumber?: string | null;
+    carrier?: string | null;
+  };
+  /**
+   * Website published — A website was published.
+   *
+   * Requires the `websites.read` grant.
+   */
+  "website.published": Record<string, unknown>;
+};
+
+/** The name of any event an app can receive. */
+export type PlatformEventName = keyof PlatformEventMap;
+
+/** The body carried by one named event. */
+export type PlatformEventData<E extends PlatformEventName> = PlatformEventMap[E] & { partial?: boolean };
+
+/** Which grant unlocks each event, for error messages and docs. */
+export const PLATFORM_EVENT_PERMISSIONS: Record<PlatformEventName, string> = {
+  "affiliate.applied": "affiliates.read",
+  "checkout.abandoned": "products.read",
+  "checkout.recovered": "products.read",
+  "collection.submission": "collections.read",
+  "community_post.created": "community.new_post",
+  "community_reply.created": "community.new_comment",
+  "contact_message.created": "contacts.read",
+  "contact.form_submitted": "forms.read",
+  "contact.quiz_completed": "contacts.read",
+  "contact.tag_added": "contacts.read",
+  "course.completed": "courses.read",
+  "course.lesson_progressed": "courses.read",
+  "dispute.created": "income.read",
+  "document.completed": "deals.read",
+  "email.clicked": "emails.read",
+  "email.opened": "emails.read",
+  "event_ticket_order.paid": "events.read",
+  "membership_tier.archived": "membership.tier_archived",
+  "membership_tier.created": "membership.tier_created",
+  "message.received": "contacts.read",
+  "moderation.report_created": "community.content_reported",
+  "order.paid": "products.read",
+  "payout.settled": "income.read",
+  "post.created": "membership.new_post",
+  "refund.failed": "income.read",
+  "refund.succeeded": "income.read",
+  "review_submitted": "reviews.read",
+  "review.published": "reviews.read",
+  "shipping.status_updated": "products.read",
+  "website.published": "websites.read",
+};
+
+/** 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/types/models.ts

@@ -88,6 +88,44 @@ export type PaymentFlowResult = PaymentStartResponse & {
   provider?: PaymentProviderName;
 };
 
+/**
+ * One coupon that ACTUALLY applied to a checkout, exactly as the ticket,
+ * booking and course pillars report it. Entered codes and automatic (no-code)
+ * discounts are reported identically — which is the only way a buyer ever finds
+ * out an automatic discount happened, since nothing else names it.
+ *
+ * `discountKind` is the engine's kind (`simple`, `free_shipping`, `bogo`,
+ * `volume`, `membership_grant`), kept as a string so a new kind added on the
+ * server does not fail to type-check here.
+ */
+export type AppliedDiscountCoupon = {
+  code: string;
+  discountKind: string;
+  /** MAJOR units — this coupon's own contribution, not the running total. */
+  discountAmount: number;
+};
+
+/**
+ * What a pillar's pre-payment call reports about pricing after discounts.
+ * `POST /public/events/:id/orders`, `POST /public/coaching/products/:id/booking/update`
+ * and `POST /public/courses/:id/booking/update` all return this same shape
+ * (S.3, `89a721af`).
+ *
+ * Every figure here is the SERVER'S, in major units. Nothing in the UI
+ * recomputes a discount: a buyer-visible number that disagrees with the charge
+ * is worse than no number at all.
+ */
+export type PillarDiscountQuote = {
+  /** GROSS, before any discount. */
+  subTotal: number;
+  /** NET — what the buyer is being asked to pay. */
+  totalAmount: number;
+  /** The whole discount, summed across `appliedCoupons`. */
+  discountAmount: number;
+  couponId: string | null;
+  appliedCoupons: AppliedDiscountCoupon[];
+};
+
 export enum ProductDeliveryType {
   Digital = "digital",
   Physical = "physical",
@@ -265,9 +303,40 @@ export interface PublicAuthState {
   } | null;
 }
 
+/**
+ * What `register` returns: the platform emailed a 6-digit code and issued NO
+ * session. Collect the code and call `verifyRegistration` — there is no variant
+ * of signup that logs a fan straight in.
+ */
+export type PublicAuthChallenge = { status: "verify_email"; email: string };
+
 export interface PublicAuthContextType extends PublicAuthState {
+  /**
+   * @deprecated Broken — do not use. Fan login is a two-step code flow, so
+   * `POST /public/sessions` returns `{ message, email }` and never a token; this
+   * method still expects one and will store `undefined`. Use
+   * `validateLoginCredentials` (emails the code) then `verifyLoginCode`.
+   */
   login: (data: LoginInput & { profileId: string }) => Promise<{ smartLinkPath: string | undefined }>;
-  register: (data: PublicCreateAccountInput) => Promise<{ smartLinkPath: string | undefined }>;
+  /**
+   * Step 1 of 2. Creates the account and emails a code; issues no session.
+   * Returns the same challenge whether or not the address is already known to the
+   * platform, so the response can't be used to discover registered emails.
+   */
+  register: (data: PublicCreateAccountInput) => Promise<PublicAuthChallenge>;
+  /**
+   * Step 2 of 2. Redeems the emailed code, signs the fan in, and applies what the
+   * signup earned (member identity, a membership from `couponCode`, consent) —
+   * which is why the coupon/consent flags are repeated here.
+   */
+  verifyRegistration: (data: {
+    email: string;
+    code: string;
+    profileId?: string;
+    couponCode?: string;
+    acceptedTerms?: boolean;
+    acceptedPrivacy?: boolean;
+  }) => Promise<{ smartLinkPath: string | undefined }>;
   validateLoginCredentials: (data: LoginInput & { profileId: string }) => Promise<string>;
   verifyLoginCode: (email: string, code: string, profileId: string) => Promise<{ smartLinkPath: string | undefined }>;
   resendLoginCode: (email: string) => Promise<void>;
@@ -385,8 +454,18 @@ export type CollectionSearchResult = PaginatedData<CollectionEntry> & {
 
 // A leaf { field, op, value } or an and/or group — the structured filter tree.
 export type CollectionFilterOp =
-  | "eq" | "ne" | "gt" | "gte" | "lt" | "lte"
-  | "in" | "between" | "contains" | "startsWith" | "arrayContains" | "isNull";
+  | "eq"
+  | "ne"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "in"
+  | "between"
+  | "contains"
+  | "startsWith"
+  | "arrayContains"
+  | "isNull";
 export type CollectionFilterNode =
   | { and: CollectionFilterNode[] }
   | { or: CollectionFilterNode[] }
@@ -772,6 +851,23 @@ export interface IEvent {
   id: string;
   profileId: string;
   dateTime: string;
+  /**
+   * When the event ends. Nullable — plenty of events are published with only a
+   * start. Calendar links fall back to a default duration when it is absent.
+   */
+  endDateTime: string | null;
+  /** Doors/arrival time, when the host publishes one separately from the start. */
+  doorsOpenAt: string | null;
+  /**
+   * Event lifecycle (mirrors the backend `EVENT_STATUS` const — Forge cannot
+   * import from the API, so the union is restated here).
+   * `draft` never reaches a public surface.
+   */
+  status: "draft" | "scheduled" | "on_sale" | "sold_out" | "cancelled" | "completed";
+  /** Set when the host cancels; distinct from `archivedAt` (a hide-from-lists flag). */
+  cancelledAt: string | null;
+  /** Host-supplied reason shown to ticket-holders on a cancelled event. */
+  cancellationReason: string | null;
   timezone?: string;
   type: "physical" | "virtual" | "hybrid";
   ticketSaleMessage?: string;
@@ -1052,6 +1148,17 @@ export type ITicketOrder = {
   taxInclusive?: boolean;
   currency?: string;
   status: OrderStatus;
+  /**
+   * Refund tracking, written by the refund service and returned by the public
+   * finalize endpoint (`getOrderById` is `selectAll` over the order row).
+   *
+   * These are what tell a refund-voided `cancelled` order apart from an
+   * abandoned one — `status` alone cannot. See `getTicketOrderOutcome`.
+   * `refundedAmountCents` is a bigint column, so it arrives as a string.
+   */
+  refundedAmountCents?: number | string | null;
+  refundState?: "none" | "partial" | "full" | string | null;
+  lastRefundedAt?: string | null;
   customerName: string;
   customerEmail: string;
   createdAt: string;

package/src/ui/headless/auth/useSignupForm.ts

@@ -13,10 +13,17 @@ export interface UseSignupFormOptions {
   requireAcceptance?: boolean;
 }
 
-/** Headless account signup. Bring your own UI (or use the styled <SignupForm>). */
+/**
+ * Headless account signup. Bring your own UI (or use the styled <SignupForm>).
+ *
+ * TWO STEPS: `submit()` creates the account and the platform emails a 6-digit
+ * code — no session yet. `awaitingCode` then flips true; collect the code into
+ * `code` and call `submitCode()`, which signs the fan in and fires `onSuccess`.
+ * Render the code input whenever `awaitingCode` is true.
+ */
 export function useSignupForm(opts: UseSignupFormOptions = {}) {
   const profileId = useForge().profileId ?? "";
-  const { register } = usePublicAuth();
+  const { register, verifyRegistration } = usePublicAuth();
 
   const [firstName, setFirstName] = useState("");
   const [lastName, setLastName] = useState("");
@@ -25,6 +32,9 @@ export function useSignupForm(opts: UseSignupFormOptions = {}) {
   const [acceptedTerms, setAcceptedTerms] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
+  // Step 2: set once the code has been emailed.
+  const [awaitingCode, setAwaitingCode] = useState(false);
+  const [code, setCode] = useState("");
 
   const requireAcceptance = opts.requireAcceptance ?? true;
 
@@ -48,7 +58,7 @@ export function useSignupForm(opts: UseSignupFormOptions = {}) {
     }
     setIsSubmitting(true);
     try {
-      const { smartLinkPath } = await register({
+      await register({
         email: email.trim(),
         password,
         firstName: firstName.trim(),
@@ -59,7 +69,8 @@ export function useSignupForm(opts: UseSignupFormOptions = {}) {
         acceptedTerms: true,
         acceptedPrivacy: true,
       });
-      opts.onSuccess?.(smartLinkPath);
+      // No session yet — the emailed code is the next step.
+      setAwaitingCode(true);
     } catch (e) {
       setError(msg(e) || "Could not create your account.");
     } finally {
@@ -67,6 +78,55 @@ export function useSignupForm(opts: UseSignupFormOptions = {}) {
     }
   };
 
+  /** Step 2: redeem the emailed code. Signs the fan in and fires `onSuccess`. */
+  const submitCode = async () => {
+    setError(null);
+    if (!/^\d{6}$/.test(code.trim())) {
+      setError("Enter the 6-digit code we emailed you.");
+      return;
+    }
+    setIsSubmitting(true);
+    try {
+      const { smartLinkPath } = await verifyRegistration({
+        email: email.trim(),
+        code: code.trim(),
+        profileId,
+        // Repeated here because this is the request that actually applies them.
+        couponCode: opts.couponCode,
+        acceptedTerms: true,
+        acceptedPrivacy: true,
+      });
+      opts.onSuccess?.(smartLinkPath);
+    } catch (e) {
+      setError(msg(e) || "That code did not work.");
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  /** Re-send a code (throttled to one per 60s server-side). */
+  const resendCode = async () => {
+    setError(null);
+    setIsSubmitting(true);
+    try {
+      await register({
+        email: email.trim(),
+        password,
+        firstName: firstName.trim(),
+        lastName: lastName.trim(),
+        profileId,
+        membershipTierId: opts.membershipTierId,
+        couponCode: opts.couponCode,
+        acceptedTerms: true,
+        acceptedPrivacy: true,
+      });
+    } catch (e) {
+      setError(msg(e) || "Could not resend the code.");
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
   return {
     firstName,
     setFirstName,
@@ -81,5 +141,10 @@ export function useSignupForm(opts: UseSignupFormOptions = {}) {
     error,
     isSubmitting,
     submit,
+    awaitingCode,
+    code,
+    setCode,
+    submitCode,
+    resendCode,
   };
 }