@tribe-nest/forge 3.21.0 → 3.23.0

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;
@@ -80,6 +101,17 @@ export type PaymentStartResponse = {
   shippingCosts?: { deliveryGroupId: string; amount: number; currency: string }[];
   /** Authoritative sales-tax quote for this charge (all wired pillars). */
   taxQuote?: PublicTaxQuote;
+  /**
+   * When the reserved stock goes back on sale, ISO-8601 — the RESTARTED clock,
+   * measured from the card form rather than from when the cart was assembled,
+   * so this supersedes whatever the create call reported.
+   *
+   * `null` (or absent, on an older API) when this order holds no inventory:
+   * a digital/service-only cart, an already-settled free order, or a profile
+   * with the holds switch off. Nothing may show a countdown in that case —
+   * "no reservation" is not "expires now".
+   */
+  holdExpiresAt?: string | null;
 };
 
 /** Normalized result surfaced by usePaymentFlow. */
@@ -825,6 +857,11 @@ export type IPublicProduct = {
   height?: number;
   dimensionUnit?: string;
   shippingCountries?: string[] | null;
+  /**
+   * Members-only restriction, from `GET /public/products` and the detail read.
+   * `null`/absent when nothing gates it. See {@link PublicMembershipGate}.
+   */
+  membershipGate?: PublicMembershipGate | null;
 };
 
 export type QuestionnaireQuestion = {
@@ -885,6 +922,40 @@ export type CoachingProduct = {
   cancellation?: CancellationTermsView | null;
 };
 
+// ---- Membership gates (S.4) --------------------------------------------------
+
+/**
+ * `sign_in_required` — the server does not know who the caller is, so they may
+ * already be a member. `membership_required` — it does, and they are not.
+ *
+ * Same outcome, different next action. That is the entire reason the API
+ * distinguishes them instead of sending one "denied", and a renderer that
+ * collapses them either tells a signed-in member to sign in (a loop with no
+ * exit) or asks an anonymous visitor to buy a membership they may already hold.
+ */
+export type MembershipGateReason = "membership_required" | "sign_in_required";
+
+/**
+ * A members-only restriction, as announced by a PUBLIC read.
+ *
+ * Present on tickets, events, products and courses. `null` on anything ungated,
+ * and on everything in a workspace where the gates switch is off — so a surface
+ * that has never heard of this field behaves exactly as it did before.
+ *
+ * The item is ANNOUNCED, never hidden: "Gold members get first refusal on the
+ * vinyl" only works as an offer if non-members can see it. Which means the
+ * storefront owes the buyer the badge AND the way out of it — see
+ * `buildMembershipGateNotice` in `ui/format/membershipGate`.
+ */
+export type PublicMembershipGate = {
+  /** Which tiers unlock it. ANY one is enough — tiers are alternatives, never components. */
+  requiredTierIds: string[];
+  /** True when THIS caller may buy. */
+  allowed: boolean;
+  /** `null` exactly when `allowed`. */
+  reason: MembershipGateReason | null;
+};
+
 export type PublicCourseLesson = {
   id: string;
   title: string;
@@ -918,6 +989,15 @@ export type PublicCourse = {
   modules?: PublicCourseModule[];
   /** Rating aggregate — present on the detail endpoint, null until first published review. */
   reviewAggregate?: IReviewAggregate | null;
+  /**
+   * Members-only restriction — present on the course DETAIL read.
+   *
+   * A live gate locks the content even for someone holding a grant, because
+   * "this course is part of Gold" is a condition for access rather than a
+   * one-off unlock. So a lapsed member sees the outline and this gate, and the
+   * page owes them the way back in. See {@link PublicMembershipGate}.
+   */
+  membershipGate?: PublicMembershipGate | null;
 };
 
 // ---- Blog --------------------------------------------------------------------
@@ -1004,6 +1084,14 @@ export interface IEvent {
   timezone?: string;
   type: "physical" | "virtual" | "hybrid";
   ticketSaleMessage?: string;
+  /**
+   * Members-only restriction on the WHOLE event — no tier of it sells to a
+   * non-member. Distinct from `ITicket.membershipGate`, which restricts one tier
+   * alongside public ones, and the two are asserted separately at checkout: a
+   * page that collapses them badges every tier on a members-only event, or none
+   * on a members-only tier. Present on the detail read only.
+   */
+  membershipGate?: PublicMembershipGate | null;
   questionnaire?: {
     id: string;
     question: string;
@@ -1019,6 +1107,16 @@ export interface IEvent {
     country: string;
     zipCode?: string;
   };
+  /**
+   * The host asks for one NAME PER PASS at checkout (Events 2.1).
+   *
+   * Optional because every event that predates the feature comes down without
+   * it, and because a renderer must treat "absent" as "do not ask" — an event
+   * that has not opted in must be unaffected by the field existing at all. A
+   * checkout that ignores this ships four passes in the buyer's name and the
+   * artist's door list is wrong; see `ui/format/attendees.ts`.
+   */
+  collectAttendeeDetails?: boolean;
   title: string;
   description?: string;
   actionText: string;
@@ -1038,6 +1136,52 @@ export interface IEvent {
    * must not assume it is present.
    */
   bookingFee?: IBookingFee | null;
+  /**
+   * This event's `.ics` address, in both forms — the DETAIL endpoint only.
+   *
+   * `calendarUrl` is the https download; `calendarWebcalUrl` is the same
+   * address under the scheme iOS and macOS route to Calendar. Apple publishes
+   * no template URL the way Google and Microsoft do, so without these an
+   * add-to-calendar control has no Apple option at all — which is exactly the
+   * state every surface in this product was in until they existed.
+   *
+   * Not derivable client-side: the address carries a keyed HMAC. Optional
+   * because `useEvents()` (the list) deliberately does not mint one, and null
+   * for a cancelled show, where the feed would 404 anyway.
+   */
+  calendarUrl?: string | null;
+  calendarWebcalUrl?: string | null;
+  /**
+   * Whether this event has a presale behind a code, and whether the code sent
+   * with THIS request opened it (1.2).
+   *
+   * Present only on the DETAIL endpoint, and only there because it is the only
+   * page with a box to type a code into. Absent on `useEvents()`.
+   *
+   * Neither field is derivable from `tickets`: a hidden tier is filtered out
+   * server-side (so a presale-only event looks like an event with no tickets at
+   * all), and a VISIBLE code-gated tier is already listed (so the right code
+   * changes nothing on screen). A renderer that guessed would either show a code
+   * box on every event or call a correct code wrong.
+   */
+  presale?: IEventPresaleState;
+}
+
+/**
+ * The two facts a storefront needs to offer a presale-code box.
+ *
+ * It carries nothing about the codes themselves — not how many exist, not which
+ * tier a code opened. A visitor guessing learns only "not a code for this
+ * event", which is what they would learn by trying to check out anyway.
+ */
+export interface IEventPresaleState {
+  /** At least one live tier is code-gated. FALSE means: render no box at all. */
+  hasCodedTiers: boolean;
+  /**
+   * `null` when no code was sent — a first page load must not open with a
+   * rejection. `false` is the only value that should show "not valid".
+   */
+  codeAccepted: boolean | null;
 }
 
 // ---- Event series ------------------------------------------------------------
@@ -1125,9 +1269,56 @@ 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
+   * because a presale code revealed it — the server filters hidden tiers out of
+   * every response that did not carry the right code.
+   *
+   * Worth badging: a buyer who has just unlocked something should be able to
+   * SEE what unlocked, otherwise a correct code looks like it did nothing.
+   */
+  isHidden?: boolean;
+  /**
+   * Members-only restriction on THIS tier — the members-only ticket alongside
+   * public ones. Present on the event DETAIL read; absent on list endpoints,
+   * which quote no ticket and offer no buy button.
+   *
+   * A gated tier stays in the list on purpose: hiding it kills the upsell that
+   * is the whole reason to sell a members-only ticket. So a renderer must badge
+   * it and offer the resolving action — sign in, or view the tier — rather than
+   * let the buyer discover the gate by being refused at payment. See
+   * {@link PublicMembershipGate}.
+   */
+  membershipGate?: PublicMembershipGate | null;
 };
 
 // ---- Invoices ----------------------------------------------------------------
@@ -1423,6 +1614,13 @@ export type CoachingBooking = {
   productTitle?: string | null;
   durationMinutes?: number | null;
   timezone?: string | null;
+  /**
+   * The session's `.ics`, both forms — see {@link CalendarFeedLinks}. Null
+   * unless the booking is CONFIRMED: a held slot is not a session, and offering
+   * to diarise a cancelled one is worse than offering nothing.
+   */
+  calendarUrl?: string | null;
+  calendarWebcalUrl?: string | null;
 };
 
 export type CourseBooking = {

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