@tribe-nest/forge 1.13.0

package/src/types/models.ts

@@ -0,0 +1,1313 @@
+// Core domain/data model types — owned by Forge (the base SDK layer).
+// `frontend-shared` re-exports these so its existing imports keep working,
+// which is what flips the dependency to frontend-shared → forge.
+
+export type ProfileAddress = {
+  street: string;
+  city: string;
+  state: string;
+  zipCode?: string;
+  country: string;
+};
+
+export type PWAConfig = {
+  name: string;
+  shortName: string;
+  description: string;
+  icon192: string;
+  icon512: string;
+  icon96: string;
+  screenshotWide1280X720: string;
+  screenshotNarrow750X1334: string;
+};
+
+export enum PaymentProviderName {
+  Stripe = "stripe",
+  Paystack = "paystack",
+}
+
+// ---- Sales tax (financial back-office) ----------------------------------------
+
+/** One jurisdiction line of a checkout tax quote. `amountCents` is MINOR units
+ * (matches the backend `TaxBreakdownItem` passed through unchanged). */
+export type TaxBreakdownEntry = {
+  jurisdiction: string;
+  /** Decimal rate, e.g. 0.19 for 19%. */
+  rate: number;
+  amountCents: number;
+};
+
+/**
+ * The authoritative checkout tax quote every pillar start-payment response now
+ * returns (`taxQuote`). All amounts are MAJOR units in `currency` — the charged
+ * currency. `pricesIncludeTax` selects inclusive (EU-style: the total already
+ * contains `tax`) vs exclusive (US-style: `tax` was added on top) display.
+ * The charged amount already reflects this quote — display only, never used
+ * for charge math on the client.
+ */
+export type PublicTaxQuote = {
+  subtotal: number;
+  tax: number;
+  total: number;
+  currency: string;
+  pricesIncludeTax: boolean;
+  taxBreakdown: TaxBreakdownEntry[];
+};
+
+/**
+ * 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`.
+ */
+export type PaymentStartResponse = {
+  paymentSecret: string;
+  paymentId: string;
+  paymentProvider?: PaymentProviderName;
+  paymentProviderName?: PaymentProviderName;
+  amount?: number;
+  currency?: string;
+  // Domain-specific extras (present only for the relevant flow):
+  orderId?: string;
+  bookingId?: string;
+  donationPaymentId?: string;
+  totalAmount?: number;
+  subTotal?: number;
+  feeAmount?: number;
+  isFreeCheckout?: boolean;
+  shippingCosts?: { deliveryGroupId: string; amount: number; currency: string }[];
+  /** Authoritative sales-tax quote for this charge (all wired pillars). */
+  taxQuote?: PublicTaxQuote;
+};
+
+/** Normalized result surfaced by usePaymentFlow. */
+export type PaymentFlowResult = PaymentStartResponse & {
+  /** Provider resolved from paymentProvider | paymentProviderName. */
+  provider?: PaymentProviderName;
+};
+
+export enum ProductDeliveryType {
+  Digital = "digital",
+  Physical = "physical",
+  Service = "service",
+}
+
+/**
+ * The artist/tenant profile. Consolidates the two `Profile` declarations that
+ * were interface-merged in the old `frontend-shared/src/types.ts` (the base
+ * fields + `avatar`).
+ */
+export interface Profile {
+  id: string;
+  name: string;
+  paymentProviderName: PaymentProviderName;
+  paymentProviderPublicKey: string;
+  pwaConfig: PWAConfig;
+  address: ProfileAddress;
+  stripeAccountId: string;
+  paystackAccountId: string;
+  currency?: string;
+  subdomain: string;
+  avatar?: string;
+  isDemo?: boolean;
+  /** Store display mode from sales-tax settings: true = listing prices already
+   * contain tax ("incl. VAT" style). Display-only; carried on the public
+   * website payload so blocks can render the right form before checkout. */
+  pricesIncludeTax?: boolean;
+}
+
+export type ApiError = {
+  response: {
+    data: {
+      message: string;
+    };
+  };
+};
+
+// ---- Currency ----------------------------------------------------------------
+
+export enum Currency {
+  USD = "USD",
+  EUR = "EUR",
+  GBP = "GBP",
+  CAD = "CAD",
+  AUD = "AUD",
+  NZD = "NZD",
+  CHF = "CHF",
+  JPY = "JPY",
+  NGN = "NGN",
+  GHS = "GHS",
+  ZAR = "ZAR",
+  KES = "KES",
+}
+
+export const SUPPORTED_CURRENCIES = [
+  Currency.USD,
+  Currency.EUR,
+  Currency.GBP,
+  Currency.CAD,
+  Currency.AUD,
+  Currency.NZD,
+  Currency.CHF,
+  Currency.JPY,
+  Currency.NGN,
+  Currency.GHS,
+  Currency.ZAR,
+  Currency.KES,
+];
+
+export const currencySymbol: Record<Currency, string> = {
+  [Currency.USD]: "$",
+  [Currency.EUR]: "€",
+  [Currency.GBP]: "£",
+  [Currency.CAD]: "CA$",
+  [Currency.AUD]: "AU$",
+  [Currency.NZD]: "NZ$",
+  [Currency.CHF]: "₣",
+  [Currency.JPY]: "¥",
+  [Currency.NGN]: "₦",
+  [Currency.GHS]: "GH₵",
+  [Currency.ZAR]: "R",
+  [Currency.KES]: "KES",
+};
+
+// ---- Membership --------------------------------------------------------------
+
+export type MembershipBenefit = {
+  id: string;
+  title: string;
+};
+
+export type MembershipTier = {
+  id: string;
+  name: string;
+  description: string;
+  priceMonthly?: number;
+  priceYearly?: number;
+  payWhatYouWant: boolean;
+  payWhatYouWantMinimum?: number;
+  payWhatYouWantMaximum?: number;
+  payWhatYouWantYearlyMinimum?: number;
+  payWhatYouWantYearlyMaximum?: number;
+  benefits: MembershipBenefit[];
+  smartLinkPath?: string;
+  smartLinkId?: string;
+  welcomeMessageSubject?: string | null;
+  welcomeMessageContent?: string | null;
+  cancellationMessageSubject?: string | null;
+  cancellationMessageContent?: string | null;
+};
+
+export interface Membership {
+  id: string;
+  membershipTierId: string;
+  profilePaymentSubscriptionId?: string;
+  paymentProviderSubscriptionId?: string;
+  endDate: string;
+  status: string;
+  membershipTier: MembershipTier;
+  startDate: string;
+  subscriptionAmount: number;
+  subscriptionCurrency: string;
+  billingCycle: string;
+}
+
+// ---- Public auth -------------------------------------------------------------
+
+export interface PublicAuthUser {
+  email: string;
+  firstName: string;
+  lastName: string;
+  kind: string;
+  status: string;
+  createdAt: string;
+  updatedAt: string;
+  id: string;
+  membership?: Membership;
+}
+
+export type UpdateLocalUserPayload = Pick<PublicAuthUser, "firstName">;
+
+// Auth input shapes. The zod schemas + react-hook-form resolvers stay in
+// frontend-shared/src/schema/auth (the form layer); Forge only needs the shapes.
+export type LoginInput = {
+  email: string;
+  password: string;
+};
+
+export type PublicCreateAccountInput = {
+  email: string;
+  password: string;
+  firstName: string;
+  lastName: string;
+  profileId: string;
+  membershipTierId?: string;
+  couponCode?: string;
+  acceptedTerms?: boolean;
+  acceptedPrivacy?: boolean;
+};
+
+export interface PublicAuthState {
+  isAuthenticated: boolean;
+  isInitialized: boolean;
+  user: PublicAuthUser | null;
+  isLoading: boolean;
+  errorMessage: string | null;
+  initialize: () => Promise<boolean>;
+  userSelectedCurrency: Currency | null;
+  setUserSelectedCurrency: (currency: Currency) => void;
+  currencies: {
+    supportedCurrencies: Currency[];
+    userCurrency: Currency;
+    exchangeRates: Record<Currency, Record<Currency, number>>;
+  } | null;
+}
+
+export interface PublicAuthContextType extends PublicAuthState {
+  login: (data: LoginInput & { profileId: string }) => Promise<{ smartLinkPath: string | undefined }>;
+  register: (data: PublicCreateAccountInput) => 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>;
+  logout: (persist?: boolean) => Promise<void>;
+  updateLocalUser: (data: UpdateLocalUserPayload) => void;
+  clearErrorMessage: () => void;
+  refetchUser: () => Promise<void>;
+}
+
+export type ActionMap<M extends { [index: string]: unknown }> = {
+  [Key in keyof M]: M[Key] extends undefined
+    ? {
+        type: Key;
+      }
+    : {
+        type: Key;
+        payload: M[Key];
+      };
+};
+
+// ---- Public content / commerce data model -----------------------------------
+
+export type PaginatedData<T> = {
+  data: T[];
+  total: number;
+  hasNextPage: boolean;
+  page: number;
+  nextPage: number | null;
+  pageSize: number;
+};
+
+// --- CMS collections (custom content types + entries) ---
+
+export type CollectionFieldType =
+  | "text"
+  | "richtext"
+  | "number"
+  | "boolean"
+  | "date"
+  | "select"
+  | "multiselect"
+  | "tags"
+  | "media"
+  | "geo"
+  | "reference"
+  | "group"
+  | "list";
+
+export type CollectionField = {
+  id: string;
+  collectionId: string;
+  key: string;
+  label: string;
+  type: CollectionFieldType;
+  section: string | null;
+  description: string | null;
+  placeholder: string | null;
+  options: Record<string, unknown> | null;
+  validation: Record<string, unknown> | null;
+  isTitle: boolean;
+  isSearchable: boolean;
+  isFilterable: boolean;
+  isSortable: boolean;
+  // Privacy tier. The public API only ever returns `public` fields — `private`
+  // fields are stripped server-side — so consumers won't normally see this set
+  // to `private`; it's here for completeness/admin surfaces.
+  visibility?: "public" | "private";
+  order: number;
+};
+
+/** A collection definition + its ordered field schema (from the `…/schema` endpoint). */
+export type Collection = {
+  id: string;
+  profileId: string;
+  name: string;
+  slug: string;
+  singular: string | null;
+  plural: string | null;
+  kind: "entity" | "taxonomy";
+  icon: string | null;
+  settings: Record<string, unknown>;
+  // `private` collections 404 on the public API, so a public consumer only ever
+  // receives `public` ones; present for completeness.
+  visibility?: "public" | "private";
+  publishedAt: string | null;
+  fields: CollectionField[];
+};
+
+/** A single row in a collection. `data` is keyed by the collection's field keys. */
+export type CollectionEntry = {
+  id: string;
+  collectionId: string;
+  profileId: string;
+  slug: string;
+  status: "draft" | "published";
+  data: Record<string, unknown>;
+  publishedAt: string | null;
+  /** Metres from the `near` point — present only on distance/geo queries. */
+  distance?: number;
+  /** Expanded reference fields (present only when `expand` was requested). */
+  expanded?: Record<string, unknown>;
+  /** Reverse-relation rows (present only when `reverse` was requested). */
+  related?: Record<string, unknown[]>;
+};
+
+export type CollectionFacet = { value: string; count: number };
+
+/** Result of a collection entry search — a page of entries plus facet counts. */
+export type CollectionSearchResult = PaginatedData<CollectionEntry> & {
+  facets: Record<string, CollectionFacet[]>;
+  /** Stable cursor for the next page (present only for cursor pagination). */
+  nextCursor?: string | null;
+};
+
+// 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";
+export type CollectionFilterNode =
+  | { and: CollectionFilterNode[] }
+  | { or: CollectionFilterNode[] }
+  | { field: string; op: CollectionFilterOp; value?: unknown };
+export type CollectionSortKey = "relevance" | "distance" | { field: string; dir?: "asc" | "desc" };
+
+/**
+ * Query params for the simple `useCollectionEntries` reads (the frozen GET
+ * /entries contract — unchanged, lenient: filters it can't apply are dropped).
+ * For the richer engine (reference expansion, `select`, cursor, `mine` scope,
+ * strict validation) use `CollectionQuery` + `useCollectionQuery`.
+ */
+export type CollectionQueryParams = {
+  page?: number;
+  limit?: number;
+  q?: string; // full-text
+  filter?: Record<string, string | string[]>; // field key -> value(s)
+  range?: Record<string, { gte?: number; lte?: number }>;
+  near?: { lat: number; lng: number; radius?: number }; // radius in metres
+  sort?: string; // "field" | "-field" | "distance" | "relevance"
+  facets?: string[]; // field keys to return counts for
+};
+
+// Reverse relation — rows in another collection that point back at each result.
+export type CollectionReverseRelation = { collection: string; field: string; as: string; limit?: number };
+
+/**
+ * The structured query DSL for `useCollectionQuery` / the POST /query endpoint.
+ * STRICT: an undeclared field or a wrong-kind operator is a 400 (unlike the
+ * lenient GET path), so it surfaces authoring mistakes.
+ */
+export type CollectionQuery = {
+  where?: CollectionFilterNode;
+  search?: string; // full-text
+  near?: { lat: number; lng: number };
+  radius?: number; // metres
+  sort?: CollectionSortKey | CollectionSortKey[];
+  select?: string[]; // project a subset of data keys
+  expand?: string[]; // reference fields to inline (1 level)
+  reverse?: CollectionReverseRelation[]; // rows pointing back at each result
+  facets?: string[];
+  page?: number;
+  limit?: number;
+  cursor?: string; // stable keyset pagination
+  /** `mine` returns the logged-in member's own rows (drafts included). */
+  scope?: "public" | "mine";
+};
+
+/** Aggregation over a collection (group-by + metrics) — POST /aggregate. */
+export type CollectionAggregate = {
+  groupBy: 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>;
+
+export type MediaType = "image" | "video" | "audio" | "document";
+
+export type IMedia = {
+  id: string;
+  url: string;
+  size: number;
+  filename: string;
+  type: MediaType;
+  previewUrl?: string | null;
+  previewStatus?: string | null;
+};
+
+export enum ProductCategory {
+  Music = "Music",
+  Merch = "Merch",
+  Digital = "Digital",
+  Service = "Service",
+  Coaching = "Coaching",
+  Course = "Course",
+}
+
+export type PostType = "image" | "video" | "audio" | "poll";
+
+export type IPublicComment = {
+  id: string;
+  content: string;
+  createdAt: string;
+  fullName: string;
+  accountId: string;
+};
+
+/** Entity an engagement action (like/save/comment) targets. */
+export type EngagementEntityType = "post" | "product" | string;
+
+export type IPublicPost = {
+  id: string;
+  caption: string;
+  media?: IMedia[];
+  likes: number;
+  comments: number;
+  createdAt: string;
+  hasAccess: boolean;
+  type: PostType;
+  profileId: string;
+  membershipTiers: string[];
+};
+
+export type IPublicPostCollection = {
+  id: string;
+  /** Per-profile slug for deep-linking (nullable when the title wasn't slugifiable). */
+  slug: string | null;
+  hasAccess: boolean;
+  membershipTiers: string[];
+  title: string;
+  description: string | null;
+  createdAt: string;
+  updatedAt: string;
+  profileId: string;
+  media: IMedia[];
+  posts: IPublicPost[];
+};
+
+export type IPublicProductTrack = {
+  id: string;
+  title: string;
+  description: string;
+  media: IMedia[];
+  isFeatured: boolean;
+  hasExplicitContent: boolean;
+  artist: string;
+  credits: string;
+  isrcCode: string;
+};
+
+export type IPublicProductVariant = {
+  id: string;
+  deliveryType: ProductDeliveryType;
+  title: string;
+  description: string;
+  price: number;
+  media: IMedia[];
+  tracks: IPublicProductTrack[];
+  isDefault: boolean;
+  payWhatYouWant?: boolean;
+  payWhatYouWantMaximum?: number;
+  upcCode: string;
+  color: string;
+  size: string;
+  availabilityStatus: "active" | "temporarily_out_of_stock";
+};
+
+// ---- Reviews -------------------------------------------------------------------
+
+/** Reviewable entity types (v1 — events deferred). */
+export type ReviewEntityType = "product" | "course" | "coaching_product";
+
+export type ReviewSortOption = "recent" | "rating" | "helpful";
+
+/** Denormalised per-entity rating aggregate, attached to public detail responses. */
+export type IReviewAggregate = {
+  avgRating: number;
+  reviewCount: number;
+  distribution: { "1": number; "2": number; "3": number; "4": number; "5": number };
+};
+
+export type IPublicReviewReply = {
+  body: string;
+  createdAt: string;
+};
+
+/** A published review as returned by GET /public/reviews. */
+export type IPublicReview = {
+  id: string;
+  rating: number;
+  title: string | null;
+  body: string | null;
+  reviewerName: string | null;
+  isVerified: boolean;
+  helpfulCount: number;
+  publishedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  /** Creator response (one per review), null when none. */
+  reply: IPublicReviewReply | null;
+};
+
+export type IPublicReviewsPage = {
+  data: IPublicReview[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasNextPage: boolean;
+  nextPage: number | null;
+  aggregate: IReviewAggregate | null;
+};
+
+/** Context for the public review form behind an emailed token link. */
+export type IReviewRequestContext = {
+  valid: boolean;
+  status: "pending" | "sent" | "reviewed" | "expired";
+  entityType: ReviewEntityType;
+  entityId: string;
+  entityTitle: string | null;
+  profile: { id: string; name: string; subdomain: string } | null;
+  defaultReviewerName: string;
+  existingReview: {
+    rating: number;
+    title: string | null;
+    body: string | null;
+    reviewerName: string | null;
+    status: string;
+    createdAt: string;
+    canEdit: boolean;
+  } | null;
+};
+
+/** The submitter's own review as returned by POST /public/reviews. */
+export type ISubmittedReview = {
+  id: string;
+  entityType: ReviewEntityType;
+  entityId: string;
+  rating: number;
+  title: string | null;
+  body: string | null;
+  reviewerName: string | null;
+  isVerified: boolean;
+  status: string;
+  publishedAt: string | null;
+  createdAt: string;
+  /** "held_for_review" when the spam guard held the review pending moderation. */
+  heldReason: string | null;
+};
+
+export type IPublicProduct = {
+  id: string;
+  slug?: string;
+  title: string;
+  description: string;
+  category: ProductCategory;
+  media: IMedia[];
+  variants: IPublicProductVariant[];
+  artist: string;
+  credits: string;
+  publishedAt: string;
+  /** Rating aggregate — present on the detail endpoint, null until first published review. */
+  reviewAggregate?: IReviewAggregate | null;
+  shippingType?: "flat" | "dynamic";
+  shippingCost?: number;
+  weight?: number;
+  weightUnit?: string;
+  length?: number;
+  width?: number;
+  height?: number;
+  dimensionUnit?: string;
+  shippingCountries?: string[] | null;
+};
+
+export type QuestionnaireQuestion = {
+  id: string;
+  question: string;
+  type: "text" | "textarea" | "select" | string;
+  options?: string[];
+  optional?: boolean;
+};
+
+export type CoachingProduct = {
+  id: string;
+  title: string;
+  description: string;
+  price: string;
+  durationMinutes: number;
+  daysInFuture: number;
+  timezone: string;
+  bufferMinutes: number;
+  archivedAt: string | null;
+  availabilityDays: {
+    dayOfWeek: number;
+    fromTime: string;
+    toTime: string;
+  }[];
+  blockedDates: string[];
+  media: IMedia[];
+  slug: string;
+  questionnaire?: QuestionnaireQuestion[];
+  /** Rating aggregate — present on the detail endpoint, null until first published review. */
+  reviewAggregate?: IReviewAggregate | null;
+};
+
+export type PublicCourseLesson = {
+  id: string;
+  title: string;
+  description?: string | null;
+  order?: number;
+  media?: IMedia[];
+};
+
+export type PublicCourseModule = {
+  id: string;
+  title: string;
+  description?: string | null;
+  order?: number;
+  lessons?: PublicCourseLesson[];
+};
+
+export type PublicCourse = {
+  id: string;
+  title: string;
+  description: string;
+  price: number | string;
+  // Optional display-only "compare-at" price (higher than `price`). When
+  // present the storefront strikes it through next to `price`. Charging uses
+  // `price`.
+  compareAtPrice?: number | string | null;
+  publishedAt: string | null;
+  slug: string;
+  media: IMedia[];
+  questionnaire?: QuestionnaireQuestion[];
+  /** Curriculum — present on the course-detail endpoint. */
+  modules?: PublicCourseModule[];
+  /** Rating aggregate — present on the detail endpoint, null until first published review. */
+  reviewAggregate?: IReviewAggregate | null;
+};
+
+// ---- Blog --------------------------------------------------------------------
+
+export type BlogPost = {
+  id: string;
+  title: string;
+  content: string;
+  publishedAt: string | null;
+  isFeatured: boolean;
+  slug: string;
+  media: { url: string; type: string; size: number; id: string; filename: string; durationSec?: number | null }[];
+};
+
+export type BlogCategory = {
+  id: string;
+  slug: string;
+  title: string;
+  description: string | null;
+  defaultLayout: "grid" | "list" | "episodes";
+  coverImage?: { url: string } | null;
+  itunesCategory: string | null;
+  author?: string | null;
+};
+
+/** A podcast show — a podcast-type blog category, trimmed for public display. */
+export type PodcastShow = {
+  id: string;
+  slug: string;
+  title: string;
+  description: string | null;
+  coverImage?: { url: string } | null;
+  author: string | null;
+  itunesCategory: string | null;
+  episodeCount: number;
+};
+
+// ---- Events ------------------------------------------------------------------
+
+export interface IEvent {
+  id: string;
+  profileId: string;
+  dateTime: string;
+  timezone?: string;
+  type: "physical" | "virtual" | "hybrid";
+  ticketSaleMessage?: string;
+  questionnaire?: {
+    id: string;
+    question: string;
+    type: string;
+    options?: string[];
+    optional?: boolean;
+  }[];
+  address?: {
+    name: string;
+    street: string;
+    city: string;
+    state?: string;
+    country: string;
+    zipCode?: string;
+  };
+  title: string;
+  description?: string;
+  actionText: string;
+  actionLink: string;
+  archivedAt?: string;
+  createdAt: string;
+  updatedAt: string;
+  tickets: ITicket[];
+  media: IMedia[];
+  slug: string;
+}
+
+export type ITicket = {
+  id: string;
+  title: string;
+  description: string;
+  price: number;
+  // Optional display-only "compare-at" price (higher than `price`). When
+  // present the storefront strikes it through next to `price`. Charging uses
+  // `price`.
+  compareAtPrice?: number | string | null;
+  quantity: number;
+  order: number;
+  sold: number;
+  maxPerPerson: number;
+  expiresAt?: string;
+  archivedAt?: string;
+};
+
+// ---- Invoices ----------------------------------------------------------------
+
+export type InvoiceLineItem = {
+  id: string;
+  description: string;
+  quantity: string;
+  unitPrice: string;
+  amount: string;
+  sortOrder: number;
+};
+
+export type InvoiceData = {
+  id: string;
+  profileId: string;
+  invoiceNumber: string;
+  status: string;
+  dueDate: string | null;
+  issueDate: string;
+  subtotal: string;
+  taxRate: string;
+  taxAmount: string;
+  total: string;
+  currency: string;
+  notes: string | null;
+  clientName: string;
+  clientEmail: string;
+  clientCompany: string | null;
+  clientAddress: string | null;
+  paidAt: string | null;
+  lineItems: InvoiceLineItem[];
+  profileName: string;
+  profileSubdomain: string;
+  businessName: string | null;
+  businessAddress: string | null;
+  businessEmail: string | null;
+  businessPhone: string | null;
+};
+
+// ---- Cohort page -------------------------------------------------------------
+// The cohort/course student page payload. The `layout` is a serialized Craft.js
+// node tree — plain JSON data (NOT a Craft runtime dependency), so the base SDK
+// owns the shape; the renderer that consumes it lives in frontend-shared.
+
+export type CohortPageData = {
+  cohort: {
+    id: string;
+    title: string;
+    description: string | null;
+    startDate: string | null;
+    endDate: string | null;
+    timezone: string;
+    publishedAt: string | null;
+  };
+  course: {
+    id: string;
+    title: string;
+    description: string;
+    media?: Array<{ url: string; type: string }>;
+  };
+  modules: Array<{
+    id: string;
+    title: string;
+    description: string | null;
+    order: number;
+    releaseOffsetDays: number | null;
+    releaseAt: string | null;
+    lessons?: Array<{
+      id: string;
+      title: string;
+      order: number;
+      durationSeconds?: number | null;
+    }>;
+  }>;
+  announcements: Array<{
+    id: string;
+    title: string;
+    bodyHtml: string;
+    pinnedAt: string | null;
+    publishedAt: string | null;
+    createdAt: string;
+  }>;
+  sessions: Array<{
+    id: string;
+    title: string;
+    description: string | null;
+    scheduledAt: string;
+    durationMinutes: number;
+    status: string;
+  }>;
+  pricingPlans: Array<{
+    id: string;
+    title: string;
+    currency: string;
+    totalAmount: string | number;
+    installmentCount: number;
+    intervalDays: number;
+    isDefault: boolean;
+  }>;
+  progress?: {
+    completedLessonCount: number;
+    totalLessonCount: number;
+  };
+  instructor?: {
+    name: string;
+    bio: string | null;
+    avatarUrl?: string | null;
+  };
+};
+
+/** A serialized Craft.js node (plain JSON — one entry in a LayoutJson tree). */
+export type LayoutNode = {
+  type: { resolvedName: string };
+  props?: Record<string, unknown>;
+  nodes?: string[];
+  parent?: string | null;
+  isCanvas?: boolean;
+  displayName?: string;
+  custom?: Record<string, unknown>;
+  hidden?: boolean;
+  linkedNodes?: Record<string, string>;
+};
+
+export type LayoutJson = Record<string, LayoutNode>;
+
+/** The full public cohort page payload returned by `/public/cohorts/:id/page`. */
+export type CohortPagePayload = {
+  data: CohortPageData | null;
+  layout: { craftJson: LayoutJson; isPublished: boolean } | null;
+};
+
+// ---- Orders ------------------------------------------------------------------
+
+export enum OrderStatus {
+  InitiatedPayment = "initiated_payment",
+  PaymentFailed = "payment_failed",
+  Failed = "failed",
+  Paid = "paid",
+  Processing = "processing",
+  LabelPurchased = "label_purchased",
+  Shipped = "shipped",
+  Delivered = "delivered",
+  Cancelled = "cancelled",
+  Processed = "processed",
+}
+
+export type IPublicOrderItem = {
+  productId: string;
+  productVariantId: string;
+  title: string;
+  price: number;
+  coverImage?: string;
+  isGift: boolean;
+  recipientName?: string;
+  recipientEmail?: string;
+  canIncreaseQuantity: boolean;
+  quantity: number;
+  recipientMessage?: string;
+  payWhatYouWant: boolean;
+  color: string;
+  size: string;
+};
+
+export type IPublicOrder = {
+  id: string;
+  deliveryGroups: {
+    id: string;
+    deliveryType: ProductDeliveryType;
+    recipientName: string;
+    recipientEmail: string;
+    recipientMessage: string;
+    items: IPublicOrderItem[];
+    status: OrderStatus;
+    subTotal: number;
+    shippingCost: number;
+    shippingCostCurrency?: string;
+    productStoreId?: string;
+    address1?: string;
+    city?: string;
+    stateCode?: string;
+    countryCode?: string;
+    zip?: string;
+    phone?: string;
+    trackingNumber?: string;
+    carrier?: string;
+    service?: string;
+    shippingLabel?: {
+      id: string;
+      trackingNumber: string;
+      labelUrl: string;
+      carrier: string;
+      service: string;
+      rateCost: number;
+      status: string;
+    } | null;
+  }[];
+  totalAmount: number;
+  totalAmountInChargedCurrency?: number | null;
+  chargedCurrency?: string | null;
+  discountAmount?: number | null;
+  /** Order-level tax snapshot in the charged currency (major units); null pre-tax orders. */
+  taxAmount?: number | string | null;
+  taxInclusive?: boolean;
+  shippingCosts?: { deliveryGroupId: string; amount: number; currency: string }[];
+  currency?: string;
+  status: OrderStatus;
+  createdAt: string;
+  updatedAt: string;
+  customerName: string;
+  customerEmail: string;
+};
+
+export type ITicketOrderItem = {
+  id: string;
+  eventTicketId: string;
+  quantity: number;
+  price: number;
+  title: string;
+};
+
+export type ITicketOrder = {
+  id: string;
+  items: ITicketOrderItem[];
+  firstName: string;
+  lastName: string;
+  email: string;
+  totalAmount: number;
+  totalAmountInChargedCurrency?: number | string | null;
+  chargedCurrency?: string | null;
+  /** Order-level tax snapshot in the charged currency (major units); null pre-tax orders. */
+  taxAmount?: number | string | null;
+  taxInclusive?: boolean;
+  currency?: string;
+  status: OrderStatus;
+  customerName: string;
+  customerEmail: string;
+  createdAt: string;
+  updatedAt: string;
+  eventTitle: string;
+  questionnaire: {
+    id: string;
+    question: string;
+    type: string;
+    options?: string[];
+    answer?: string;
+    optional?: boolean;
+  }[];
+};
+
+/** Status of a coaching/course booking through its payment lifecycle. */
+export type BookingStatus = "reserved" | "confirmed" | "canceled" | "payment_failed";
+
+export type CoachingBooking = {
+  id: string;
+  status: BookingStatus;
+  firstName: string;
+  lastName: string;
+  email: string;
+  totalAmount: number;
+  totalAmountInChargedCurrency?: number | null;
+  chargedCurrency?: string | null;
+  /** Booking-level tax snapshot in the charged currency (major units); null pre-tax bookings. */
+  taxAmount?: number | string | null;
+  taxInclusive?: boolean;
+  /** Session slot + product details (present from the finalize endpoint). */
+  sessionStartTime?: string | null;
+  sessionEndTime?: string | null;
+  productTitle?: string | null;
+  durationMinutes?: number | null;
+  timezone?: string | null;
+};
+
+export type CourseBooking = {
+  id: string;
+  status: BookingStatus;
+  firstName: string;
+  lastName: string;
+  email: string;
+  totalAmount: number;
+  totalAmountInChargedCurrency?: number | null;
+  chargedCurrency?: string | null;
+  /** Booking-level tax snapshot in the charged currency (major units); null pre-tax bookings. */
+  taxAmount?: number | string | null;
+  taxInclusive?: boolean;
+};
+
+// ---- Course access (player) --------------------------------------------------
+
+export type CourseAccessRecord = {
+  id: string;
+  courseId: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+  currentLessonId: string | null;
+};
+
+export type CourseLessonProgress = {
+  id: string;
+  lessonId: string;
+  videoProgress: number;
+  isCompleted: boolean;
+};
+
+export type CourseLesson = {
+  id: string;
+  title: string;
+  content: string;
+  order: number;
+  media: Array<{
+    url: string;
+    type: string;
+    size: number;
+    id: string;
+    filename: string;
+  }>;
+  progress: CourseLessonProgress | null;
+};
+
+export type CourseModule = {
+  id: string;
+  title: string;
+  description: string | null;
+  order: number;
+  lessons: CourseLesson[];
+};
+
+export type CourseAccessCourse = {
+  id: string;
+  title: string;
+  description: string;
+  modules: CourseModule[];
+};
+
+export type CourseAccessData = {
+  access: CourseAccessRecord;
+  course: CourseAccessCourse;
+  progress: CourseLessonProgress[];
+};
+
+// ---- Live broadcasts (streaming) ---------------------------------------------
+
+export type ILiveEvent = {
+  id: string;
+  title: string;
+  description: string;
+  isPaid: boolean;
+};
+
+export type ILiveBroadcast = {
+  id: string;
+  realtimeConfig?: {
+    sessionId: string;
+    tracks: {
+      mid: string;
+      trackName: string;
+    }[];
+  };
+  events: {
+    eventId: string;
+    eventTitle: string;
+    eventTickets: ITicket[];
+  }[];
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  profileId: string;
+  streamTemplateId: string;
+  startedAt?: string;
+  endedAt?: string;
+  egressId: string;
+  event: ILiveEvent;
+  startDate?: string;
+  generatedThumbnailUrl?: string;
+  liveUrl?: string;
+  vodUrl?: string;
+  thumbnailUrl?: string;
+};
+
+export type IBroadcastPass = {
+  sessionId: string;
+  name: string;
+  email: string;
+};
+
+// ---- Coaching availability / booking -----------------------------------------
+
+export type BookingSlot = {
+  id: string;
+  startTime: string;
+  endTime: string;
+  coachingAvailabilityDayId: string;
+};
+
+// ---- Public forms ------------------------------------------------------------
+
+export type FormField = {
+  id: string;
+  type: string;
+  label: string;
+  description: string | null;
+  placeholder: string | null;
+  isRequired: boolean;
+  options: Array<{ id: string; label: string }> | null;
+  validation: { min?: number; max?: number; maxLength?: number } | null;
+  order: number;
+  /** Which section this field belongs to (null on legacy flat forms). */
+  sectionId?: string | null;
+};
+
+/** Edge scope: field→field jump, section→section page flow, or in-page show/hide. */
+export type FormEdgeScope = "field" | "section" | "visibility";
+
+export type FormFieldEdge = {
+  id: string;
+  scope?: FormEdgeScope;
+  sourceFieldId: string | null;
+  targetFieldId: string | null;
+  sourceSectionId?: string | null;
+  targetSectionId?: string | null;
+  /** For section edges: jump to a section, or end the form. */
+  targetKind?: "section" | "submit" | null;
+  condition: { operator: string; value: string | string[] | null } | null;
+  label: string | null;
+  sortOrder: number;
+};
+
+export type FormSection = {
+  id: string;
+  title: string | null;
+  description: string | null;
+  order: number;
+  /** The choice question this section branches on (null = linear / next). */
+  branchFieldId: string | null;
+};
+
+export type FormData = {
+  id: string;
+  title: string;
+  description: string | null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  settings: any;
+  /** Ordered sections (empty/absent on legacy flat forms). */
+  sections?: FormSection[];
+  fields: FormField[];
+  edges: FormFieldEdge[];
+};
+
+export type FormAnswerEntry = {
+  fieldId: string;
+  value: string | null;
+};
+
+// ---- Replay broadcasts -------------------------------------------------------
+
+export type ReplayBroadcast = {
+  id: string;
+  title: string;
+  startedAt: string;
+  endedAt: string | null;
+  vodUrl: string | null;
+  thumbnailUrl: string | null;
+  generatedThumbnailUrl: string | null;
+};
+
+export type ReplayData = {
+  eventPass: {
+    id: string;
+    ownerName: string;
+    ownerEmail: string;
+    eventId: string;
+    eventTicketId: string;
+  };
+  broadcasts: ReplayBroadcast[];
+};
+
+// ---- Donations & Offers ------------------------------------------------------
+
+export type PublicDonation = {
+  id: string;
+  profileId: string;
+  title: string;
+  description: string | null;
+  minimumAmount: string | null;
+  defaultAmounts: number[];
+  donateButtonText: string;
+  successMessage: string | null;
+  coverFeesEnabled: boolean;
+  isActive: boolean;
+};
+
+export type PublicOffer = {
+  id: string;
+  name: string;
+  offerType: string;
+  itemId: string;
+  ticketTypeId: string | null;
+  description: string | null;
+  buttonText: string | null;
+};
+
+// ---- Payment links -----------------------------------------------------------
+
+export type PaymentLinkData = {
+  id: string;
+  profileId: string;
+  recipientEmail: string;
+  recipientName: string;
+  amount: string;
+  currency: string;
+  message: string | null;
+  status: string;
+  paidAt: string | null;
+  createdAt: string;
+  profileName: string;
+  profileSubdomain: string;
+};