@tribe-nest/forge 2.2.0 → 3.2.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

@@ -265,9 +265,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 +416,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[] }

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

package/src/ui/headless/work/useWorkPortal.ts

@@ -1,9 +1,4 @@
-import {
-  useMutation,
-  useQuery,
-  useQueryClient,
-  type UseQueryResult,
-} from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient, type UseQueryResult } from "@tanstack/react-query";
 import { useForge } from "../../../provider/ForgeProvider";
 
 /**
@@ -113,10 +108,24 @@ export interface WorkInviteContext {
   profileName: string;
   email: string;
   firstName: string | null;
+  /**
+   * The invited address already has an account, so the invite grants portal
+   * access but cannot set a credential — render "sign in", not a password
+   * form (C10).
+   */
+  requiresExistingLogin?: boolean;
 }
 
 export interface WorkInviteAcceptResult {
-  token: string;
+  /**
+   * True when the invited address already has an account: the invite granted
+   * portal access but issued NO session, and the person signs in normally
+   * (C10). `token` is absent in that case.
+   */
+  requiresLogin?: boolean;
+  token?: string;
+  /** Rotating refresh token for the portal session (backend §7) — persist it. */
+  refreshToken?: string;
   projectId: string;
   account: { id: string; email: string; firstName: string | null; lastName: string | null };
 }
@@ -125,8 +134,7 @@ export interface WorkInviteAcceptResult {
 
 const keys = {
   projects: (profileId?: string) => ["work-portal-projects", profileId] as const,
-  report: (profileId: string | undefined, projectId: string) =>
-    ["work-portal-report", profileId, projectId] as const,
+  report: (profileId: string | undefined, projectId: string) => ["work-portal-report", profileId, projectId] as const,
   tokenReport: (token: string) => ["work-portal-token-report", token] as const,
   taskComments: (profileId: string | undefined, projectId: string, taskId: string) =>
     ["work-portal-task-comments", profileId, projectId, taskId] as const,
@@ -212,10 +220,9 @@ export function useWorkTaskComments(projectId: string, taskId: string): UseWorkT
   const query = useQuery<WorkTaskComment[]>({
     queryKey: keys.taskComments(profileId, projectId, taskId),
     queryFn: async () => {
-      const res = await client.get(
-        `/public/work/projects/${projectId}/tasks/${taskId}/comments`,
-        { params: { profileId } },
-      );
+      const res = await client.get(`/public/work/projects/${projectId}/tasks/${taskId}/comments`, {
+        params: { profileId },
+      });
       return res.data as WorkTaskComment[];
     },
     enabled: !!profileId && !!client && !!projectId && !!taskId,
@@ -255,18 +262,14 @@ export function useWorkTaskComments(projectId: string, taskId: string): UseWorkT
  * projects — GET /public/work/projects/:projectId/tasks/:taskId/attachments.
  * Tier-1 primitive: returns clean data, renders nothing.
  */
-export function useWorkTaskAttachments(
-  projectId: string,
-  taskId: string,
-): UseQueryResult<WorkTaskAttachment[]> {
+export function useWorkTaskAttachments(projectId: string, taskId: string): UseQueryResult<WorkTaskAttachment[]> {
   const { client, profileId } = useForge();
   return useQuery<WorkTaskAttachment[]>({
     queryKey: keys.taskAttachments(profileId, projectId, taskId),
     queryFn: async () => {
-      const res = await client.get(
-        `/public/work/projects/${projectId}/tasks/${taskId}/attachments`,
-        { params: { profileId } },
-      );
+      const res = await client.get(`/public/work/projects/${projectId}/tasks/${taskId}/attachments`, {
+        params: { profileId },
+      });
       return res.data as WorkTaskAttachment[];
     },
     enabled: !!profileId && !!client && !!projectId && !!taskId,