@openlup/platform 0.28.0 → 0.30.0

package/src/marketing/analytics/routePolicy.ts

@@ -0,0 +1,55 @@
+import type { AnalyticsRoutePolicyInput } from "../contracts/analytics.js";
+export type { AnalyticsRoutePolicyInput } from "../contracts/analytics.js";
+const CAMPAIGN_KEYS = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"] as const;
+const CAMPAIGN_VALUE = /^[A-Za-z0-9_-]{1,100}$/;
+const NO_ADDITIONAL_PATHS: ReadonlySet<string> = new Set();
+
+export function normalizeAnalyticsPathname(pathname: string): string {
+  const withLeadingSlash = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  const withoutTrailingSlash = withLeadingSlash.length > 1
+    ? withLeadingSlash.replace(/\/+$/, "") : withLeadingSlash;
+  return withoutTrailingSlash.toLowerCase();
+}
+
+/** Route manifests and sensitive paths are explicit host policy. */
+export function createAnalyticsRoutePolicy(input: AnalyticsRoutePolicyInput) {
+  const manifestPaths = new Set(input.publicPaths.map(normalizeAnalyticsPathname));
+  const redirectPaths = new Set(input.redirectSources.filter(source => !source.includes(":"))
+    .map(normalizeAnalyticsPathname));
+  function isSensitiveAnalyticsPath(pathname: string): boolean {
+    const capabilityPath = pathname.toLowerCase();
+    return input.privatePathPrefixes.some(prefix => pathname === prefix || pathname.startsWith(`${prefix}/`))
+      || input.privateAuthPaths.includes(pathname)
+      || input.capabilityPathPrefixes.some(prefix => capabilityPath === prefix || capabilityPath.startsWith(`${prefix}/`));
+  }
+  function isOptionalAnalyticsRouteEligible(pathname: string): boolean {
+    return !isSensitiveAnalyticsPath(pathname);
+  }
+  function isDeploymentAnalyticsRouteEligible(pathname: string,
+    additionalPublicPaths: ReadonlySet<string> = NO_ADDITIONAL_PATHS): boolean {
+    const path = normalizeAnalyticsPathname(pathname);
+    if (isSensitiveAnalyticsPath(path)) return false;
+    return manifestPaths.has(path) || redirectPaths.has(path) || additionalPublicPaths.has(path);
+  }
+  function sanitizeDeploymentAnalyticsUrl(rawUrl: string, currentOrigin: string,
+    additionalPublicPaths?: ReadonlySet<string>): string | null {
+    let base: URL;
+    let url: URL;
+    try { base = new URL(currentOrigin); url = new URL(rawUrl, base); } catch { return null; }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password
+      || url.origin !== base.origin) return null;
+    const pathname = normalizeAnalyticsPathname(url.pathname);
+    if (!isDeploymentAnalyticsRouteEligible(pathname, additionalPublicPaths)) return null;
+    const campaign = new URLSearchParams();
+    for (const key of CAMPAIGN_KEYS) {
+      const values = url.searchParams.getAll(key);
+      if (values.length === 1 && CAMPAIGN_VALUE.test(values[0]!)) campaign.set(key, values[0]!);
+    }
+    url.pathname = pathname;
+    url.search = campaign.toString();
+    url.hash = "";
+    return url.href;
+  }
+  return { isSensitiveAnalyticsPath, isOptionalAnalyticsRouteEligible,
+    isDeploymentAnalyticsRouteEligible, sanitizeDeploymentAnalyticsUrl };
+}

package/src/marketing/consentEvidence.ts

@@ -0,0 +1,36 @@
+import type { MarketingHistoricalConsentCommand, MarketingHistoricalConsentState, MarketingHistoricalConsentResult } from "./contracts/analytics.js";
+export type { MarketingHistoricalConsentCommand, MarketingHistoricalConsentState, MarketingHistoricalConsentResult } from "./contracts/analytics.js";
+import { z } from "./validation.js";
+
+const historicalTimestamp = z.string().max(80).datetime({ offset: true });
+const HISTORICAL_MIN_AGE_MS = 5 * 60 * 1000;
+
+/** Transport chronology after authorization; never changes the local consent grant. */
+export function selectMarketingHistoricalConsentTime(input: {
+  command: MarketingHistoricalConsentCommand; state: MarketingHistoricalConsentState; now: Date;
+}): MarketingHistoricalConsentResult {
+  const { command, state, now } = input;
+  if (!Number.isFinite(now.getTime())) return { kind: "hold", reason: "consent_time_invalid" };
+  let selected = command.consentedAt;
+  if (state.consent === "SUBSCRIBED") {
+    const native = historicalTimestamp.safeParse(state.nativeConsentAt);
+    if (!native.success || !Number.isFinite(Date.parse(native.data)) || Date.parse(native.data) >= now.getTime()) {
+      return { kind: "hold", reason: "provider_state_unknown" };
+    }
+    const overriding = state.suppressions.some(item => item.reason === "UNSUBSCRIBE"
+      && (item.listId === null || item.listId === command.listId));
+    if (!overriding) selected = native.data;
+    else if (Date.parse(command.consentedAt ?? "") > Date.parse(native.data)) {
+      return { kind: "hold", reason: "provider_state_unknown" };
+    }
+  }
+  const parsed = historicalTimestamp.safeParse(selected);
+  if (!parsed.success || !Number.isFinite(Date.parse(parsed.data)) || Date.parse(parsed.data) >= now.getTime()) {
+    return { kind: "hold", reason: "consent_time_invalid" };
+  }
+  // Parsing truncates fractional milliseconds; round only the age boundary up.
+  const discarded = /\.\d{3}(\d+)(?:Z|[+-]\d{2}:\d{2})$/.exec(parsed.data)?.[1];
+  const matureAt = Date.parse(parsed.data) + (discarded && /[1-9]/.test(discarded) ? 1 : 0) + HISTORICAL_MIN_AGE_MS;
+  return now.getTime() < matureAt ? { kind: "defer", retryAt: new Date(matureAt).toISOString() }
+    : { kind: "ready", providerConsentedAt: parsed.data };
+}

package/src/marketing/contactLegal.ts

@@ -0,0 +1,22 @@
+import type { ContactContent, LegalDocumentContent } from "./contracts/contactLegal.js";
+
+export function contactContent(facts: ContactContent) {
+  return {
+    supportEmail: facts.supportEmail,
+    companyLines: [
+      facts.organization.legalName,
+      facts.addressLine,
+      facts.registrationIdentifiers.map(({ label, value }) => `${label} ${value}`).join(" · "),
+      ...(facts.registrationAuthority !== undefined ? [facts.registrationAuthority] : []),
+    ],
+  };
+}
+
+export function legalDocumentContent(content: LegalDocumentContent) {
+  return {
+    title: content.title,
+    intro: content.intro,
+    sections: content.sections.map(({ title, body }) => ({ title, body })),
+    ...(content.lastUpdated !== undefined ? { lastUpdated: content.lastUpdated } : {}),
+  };
+}

package/src/marketing/contracts/acquisition.ts

@@ -0,0 +1,50 @@
+export type AcquisitionOpaqueReference = string;
+export type AcquisitionAddressReference = { source: string; reference: string; revision: string; provenance: string };
+export type AcquisitionCaseState = "submitted" | "approved" | "active" | "rejected" | "withdrawn";
+export type AcquisitionCaseProjection = {
+  contractVersion: "tester_application_v1";
+  caseRef: string;
+  contactRef: string;
+  sourceKind: "tester_application";
+  consent: { consentVersion: string; policyVersion: string; recordedAt: string; locale: "en" | "pl"; sourcePath: "/tester-application" };
+  addressReference: AcquisitionAddressReference | null;
+  state: AcquisitionCaseState;
+  version: number;
+  createdAt: string;
+  updatedAt: string;
+};
+export type AcquisitionCaseListRequest = { view: "acquisition_case_v1"; cursor?: string | undefined; limit: number };
+export type AcquisitionCaseListResponse = { contractVersion: "tester_application_v1"; cases: AcquisitionCaseProjection[]; nextCursor: string | null };
+export type AcquisitionCaseActiveCountResponse = { activeTesterCount: number };
+export type AcquisitionIdempotencyKey = string;
+export type AcquisitionSurveySubmit = { view: "acquisition_survey_v1"; caseReference: string; surveyType: "producer" | "consumer"; responseData: Record<string, unknown> };
+export type AcquisitionSurveyEvidence = {
+  evidenceReference: string;
+  caseReference: string;
+  contactReference: string;
+  surveyType: "producer" | "consumer";
+  responseDigest: string;
+  answerCount: number;
+  recordedAt: string;
+};
+export type AcquisitionSurveySubmitResponse = { contractVersion: "acquisition_survey_v1"; evidence: AcquisitionSurveyEvidence; replayed: boolean };
+export type AcquisitionSurveyListQuery = { view: "acquisition_survey_v1"; surveyType?: "producer" | "consumer" | undefined; limit: number };
+export type AcquisitionSurveyListResponse = { contractVersion: "acquisition_survey_v1"; rows: AcquisitionSurveyEvidence[]; totalCount: number };
+export type AcquisitionNewsletterConsentEvent = {
+  contractVersion: "acquisition_newsletter_consent_v1";
+  caseReference: string;
+  contactReference: string;
+  eventReference: string;
+  eventType: "subscribe" | "unsubscribe" | "suppress" | "complaint" | "update";
+  purpose: "marketing_launch_offer" | "marketing_newsletter";
+  explicitOptInEvidence: boolean;
+  occurredAt: string;
+};
+export type AcquisitionNewsletterConsentResponse = {
+  contractVersion: "acquisition_newsletter_consent_v1";
+  eventReference: string;
+  outcome: "applied" | "ignored" | "stale";
+  consentState: "granted" | "suppressed" | null;
+  auditReference: string;
+  replayed: boolean;
+};

package/src/marketing/contracts/acquisitionPorts.ts

@@ -0,0 +1,48 @@
+import type {
+  AcquisitionCaseListResponse, AcquisitionCaseProjection, AcquisitionNewsletterConsentEvent,
+  AcquisitionNewsletterConsentResponse, AcquisitionSurveyListQuery, AcquisitionSurveyListResponse,
+  AcquisitionSurveySubmit, AcquisitionSurveySubmitResponse,
+} from "./acquisition.js";
+
+export type AcquisitionCaseFailureKind =
+  | "conflict"
+  | "invalid"
+  | "not_found"
+  | "rate_limited"
+  | "unavailable";
+
+export type AcquisitionCaseResult<T> =
+  | { ok: true; value: T; replayed?: boolean }
+  | { ok: false; error: { kind: AcquisitionCaseFailureKind } };
+
+export interface AcquisitionCaseListQuery {
+  actorRef: string;
+  scope: "public_tester_application";
+  cursor?: string;
+  limit: number;
+}
+
+export interface AcquisitionCaseGetQuery {
+  actorRef: string;
+  scope: "public_tester_application";
+  caseRef: string;
+}
+
+export interface AcquisitionCasePort {
+  list(query: AcquisitionCaseListQuery): Promise<AcquisitionCaseResult<AcquisitionCaseListResponse>>;
+  get(query: AcquisitionCaseGetQuery): Promise<AcquisitionCaseResult<AcquisitionCaseProjection>>;
+  activeCount(scope: "public_tester_application"): Promise<AcquisitionCaseResult<number>>;
+  close(): Promise<void>;
+}
+
+export type AcquisitionEvidenceFailure = "invalid" | "not_found" | "conflict" | "unavailable";
+export type AcquisitionEvidenceResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: { kind: AcquisitionEvidenceFailure } };
+
+export interface AcquisitionEvidencePort {
+  submitSurvey(input: AcquisitionSurveySubmit & { idempotencyKey: string }): Promise<AcquisitionEvidenceResult<AcquisitionSurveySubmitResponse>>;
+  listSurveys(input: AcquisitionSurveyListQuery & { actorReference: string }): Promise<AcquisitionEvidenceResult<AcquisitionSurveyListResponse>>;
+  applyNewsletterConsent(input: AcquisitionNewsletterConsentEvent): Promise<AcquisitionEvidenceResult<AcquisitionNewsletterConsentResponse>>;
+  close(): Promise<void>;
+}

package/src/marketing/contracts/analytics.ts

@@ -0,0 +1,88 @@
+/** The host supplies its own literal step vocabulary. */
+export type AnalyticsStepName<StepName extends string = string> = StepName;
+export interface AnalyticsCheckoutItem { item_id: string; quantity: number }
+export interface AnalyticsPurchaseItem extends AnalyticsCheckoutItem {
+  item_variant?: string;
+  price: number;
+  discount: number;
+}
+export type AnalyticsCheckoutMode = "one_time" | "subscription";
+/** No answer describes an ended wait, without asserting payment failure. */
+export type AnalyticsPaymentWaitOutcome = "confirmed" | "refused" | "no_answer";
+export interface AnalyticsEventMap<StepName extends string = string> {
+  page_view: { page_path: string };
+  configurator_start: { entry_view: "hero" | "configurator" };
+  configurator_step_view: { step_number: number; step_name: AnalyticsStepName<StepName> };
+  begin_checkout: { checkout_mode: AnalyticsCheckoutMode; items: AnalyticsCheckoutItem[] };
+  purchase: {
+    transaction_id: string;
+    currency: string;
+    value: number;
+    shipping: number;
+    tax: number;
+    checkout_mode: AnalyticsCheckoutMode;
+    items: AnalyticsPurchaseItem[];
+  };
+  // Wait observations carry no identity, amount, currency or payment method.
+  payment_wait_start: { checkoutMode: AnalyticsCheckoutMode };
+  payment_wait_end: { outcome: AnalyticsPaymentWaitOutcome; checkoutMode: AnalyticsCheckoutMode };
+  configurator_draft_restored: { draft_context: "public" };
+  configurator_draft_save_failed: { draft_context: "public"; reason: "unavailable" | "quota" | "conflict" };
+  configurator_draft_reset: { draft_context: "public" };
+}
+export type AnalyticsEventName = keyof AnalyticsEventMap;
+
+export interface AnalyticsSinkAttemptMask { deployment: boolean; optional: boolean }
+/** Synchronous local acceptance only; never transport delivery or business acknowledgement. */
+export interface AnalyticsSinkAdmission { deployment: boolean; optional: boolean }
+export interface AnalyticsCookieConsent {
+  necessary: boolean; functional: boolean; analytics: boolean; marketing: boolean;
+}
+export type AnalyticsBrowserWindow = Pick<Window, "localStorage" | "addEventListener" | "removeEventListener"> & {
+  dataLayer?: unknown[];
+};
+export interface AnalyticsDataLayerOptions<StepName extends string = string> {
+  consentStorageKey?: string;
+  consentChangeEvent?: string;
+  /** Host wire names, analytics first then advertising in supplied order. Omission disables consent commands and optional event admission. */
+  consentSignalNames?: { analytics: string; advertising: readonly string[] };
+  eventPrefix?: string;
+  readContainerId?: () => string | null;
+  trackDeploymentEvent?: <K extends AnalyticsEventName>(event: K, properties: AnalyticsEventMap<StepName>[K]) => boolean;
+  getWindow?: () => AnalyticsBrowserWindow | undefined;
+}
+
+export interface AnalyticsRoutePolicyInput {
+  publicPaths: readonly string[];
+  redirectSources: readonly string[];
+  privatePathPrefixes: readonly string[];
+  privateAuthPaths: readonly string[];
+  capabilityPathPrefixes: readonly string[];
+}
+
+/** Only paid recap facts read by the projection; money remains the host's truth. */
+export interface PurchaseOrder {
+  orderId: string;
+  status: string;
+  paymentStatus: string | null;
+  checkoutKind: "one_time" | "subscription_initial" | "subscription_renewal" | null;
+  moneyReconciled: boolean;
+  items: Array<{ sku: string | null; variantCode: string | null; quantity: number;
+    catalogTotalGross: number; effectiveNet: number; vatRateBps: number }>;
+  totals: { tax: { amountMinor: number }; total: { amountMinor: number; currency: string } };
+}
+export type PurchaseSuppressionReason = "order_not_paid" | "payment_not_succeeded"
+  | "checkout_kind_unsupported" | "money_unreconciled" | "items_empty" | "sku_missing"
+  | "quantity_invalid" | "line_money_invalid" | "net_discount_invalid"
+  | "item_limit_exceeded" | "shipping_net_invalid";
+
+export interface MarketingHistoricalConsentCommand { consentedAt: string | null; listId: string | null }
+/** Native state literals are compatibility inputs supplied by the host adapter. */
+export interface MarketingHistoricalConsentState {
+  consent: "SUBSCRIBED" | "UNSUBSCRIBED" | "NEVER_SUBSCRIBED" | "unknown";
+  nativeConsentAt?: string | null;
+  suppressions: Array<{ reason: "UNSUBSCRIBE" | "SPAM_REPORT" | "USER_SUPPRESSED" | "HARD_BOUNCE" | "INVALID_EMAIL" | "unknown";
+    listId: string | null }>;
+}
+export type MarketingHistoricalConsentResult = { kind: "ready"; providerConsentedAt: string }
+  | { kind: "defer"; retryAt: string } | { kind: "hold"; reason: string };

package/src/marketing/contracts/contactLegal.ts

@@ -0,0 +1,41 @@
+export interface OrganizationFacts {
+  name: string;
+  legalName: string;
+  url: string;
+  logo: { url: string; contentUrl: string; width: number; height: number };
+  email: string;
+  vatID: string;
+  taxID: string;
+  areaServed: string;
+  sameAs: string[];
+  contactPoint: { email: string; contactType: string; availableLanguage: string[] };
+  address: {
+    streetAddress: string;
+    addressLocality: string;
+    postalCode: string;
+    addressRegion: string;
+    addressCountry: string;
+  };
+}
+
+export interface ContactContent {
+  organization: OrganizationFacts;
+  supportEmail: string;
+  addressLine: string;
+  registrationIdentifiers: { label: string; value: string }[];
+  registrationAuthority?: string;
+}
+
+export interface LegalDocumentContent {
+  title: string;
+  intro: string;
+  sections: { title: string; body: string }[];
+  lastUpdated?: string;
+}
+
+export interface PrivacyProcessorDisclosure {
+  processorName: string;
+  purpose: string;
+  dataCategories: string[];
+  details?: string;
+}

package/src/marketing/contracts/index.ts

@@ -0,0 +1,17 @@
+export type * from "./acquisition.js";
+export type {
+  MarketingResearchJson,
+  ResearchSurveyType,
+  AdminSurveyResponsesRequest,
+  AdminSurveyResponseRow,
+  AdminSurveyResponsesResponse,
+  ResearchSurveySubmitRequest,
+  ResearchSurveySubmitResponse,
+  MarketingResearchSurveyResponsesReadPort,
+  MarketingResearchSurveyRequestHeaders,
+  MarketingResearchSurveySubmitPort,
+} from "@openlup/core/marketing/research";
+export type * from "./acquisitionPorts.js";
+export type * from "./prelaunch.js";
+export type * from "./analytics.js";
+export type * from "./contactLegal.js";

package/src/marketing/contracts/prelaunch.ts

@@ -0,0 +1,15 @@
+export type PrelaunchAcquisitionListRequest = { view: "prelaunch_acquisition_v1"; cursor?: string | undefined; limit: number };
+export type PrelaunchAcquisitionDetailRequest = { sourceRef: string };
+export type PrelaunchAcquisitionLead = {
+  sourceRef: string;
+  contactRef: string;
+  sourceKind: "tester_application";
+  consent: { consentVersion: string; policyVersion: string; recordedAt: string; locale: "en" | "pl"; sourcePath: "/tester-application" };
+  addressReference: { source: string; reference: string; revision: string; provenance: string } | null;
+  state: "submitted" | "approved" | "active" | "rejected" | "withdrawn";
+  version: number;
+  createdAt: string;
+  updatedAt: string;
+};
+export type PrelaunchAcquisitionListResponse = { contractVersion: "prelaunch_acquisition_v1"; leads: PrelaunchAcquisitionLead[]; nextCursor: string | null };
+export type PrelaunchAcquisitionDetailResponse = { contractVersion: "prelaunch_acquisition_v1"; lead: PrelaunchAcquisitionLead };

package/src/marketing/index.ts

@@ -0,0 +1,16 @@
+export * from "./acquisitionCaseSchemas.js";
+export * from "./acquisitionEvidenceSchemas.js";
+export * from "@openlup/core/marketing/research";
+export * from "./prelaunchAcquisitionSchemas.js";
+export type * from "./contracts/acquisitionPorts.js";
+export * from "./analytics/noop.js";
+export * from "./analytics/dataLayer.js";
+export * from "./analytics/routePolicy.js";
+export * from "./analytics/purchaseFacts.js";
+export * from "./consentEvidence.js";
+export * from "./seo/serializeJsonLd.js";
+export * from "./seo/urls.js";
+export * from "./seo/metadata.js";
+export * from "./seo/jsonLd.js";
+export type * from "./contracts/contactLegal.js";
+export * from "./contactLegal.js";

package/src/marketing/prelaunchAcquisitionSchemas.ts

@@ -0,0 +1,64 @@
+import { z } from "./validation.js";
+
+export const PRELAUNCH_ACQUISITION_VIEW = "prelaunch_acquisition_v1" as const;
+export const PRELAUNCH_ACQUISITION_CONTRACT_VERSION = "prelaunch_acquisition_v1" as const;
+
+const acquisitionCaseRefSchema = z.string().regex(/^acquisition-case:[0-9a-f-]{36}$/);
+const acquisitionContactRefSchema = z.string().regex(/^acquisition-contact:[0-9a-f-]{36}$/);
+const acquisitionOpaqueRefSchema = z.string().trim().min(8).max(160)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+const acquisitionDateTimeSchema = z.string().datetime({ offset: true });
+
+export const prelaunchAcquisitionListRequestSchema = z.object({
+  view: z.literal(PRELAUNCH_ACQUISITION_VIEW),
+  cursor: acquisitionOpaqueRefSchema.optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(25),
+}).strict();
+
+export const prelaunchAcquisitionDetailRequestSchema = z.object({
+  sourceRef: acquisitionCaseRefSchema,
+}).strict();
+
+export const prelaunchAcquisitionLeadSchema = z.object({
+  sourceRef: acquisitionCaseRefSchema,
+  contactRef: acquisitionContactRefSchema,
+  sourceKind: z.literal("tester_application"),
+  consent: z.object({
+    consentVersion: z.string().min(1).max(64),
+    policyVersion: z.string().min(1).max(64),
+    recordedAt: acquisitionDateTimeSchema,
+    locale: z.enum(["en", "pl"]),
+    sourcePath: z.literal("/tester-application"),
+  }).strict(),
+  addressReference: z.object({
+    source: z.string().trim().min(1).max(48).regex(/^[a-z][a-z0-9_-]*$/),
+    reference: acquisitionOpaqueRefSchema,
+    revision: z.string().trim().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/),
+    provenance: z.string().trim().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/),
+  }).strict().nullable(),
+  state: z.enum(["submitted", "approved", "active", "rejected", "withdrawn"]),
+  version: z.number().int().positive(),
+  createdAt: acquisitionDateTimeSchema,
+  updatedAt: acquisitionDateTimeSchema,
+}).strict().superRefine((value, context) => {
+  if (value.state !== "withdrawn" && value.addressReference === null) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ["addressReference"], message: "active case requires address reference" });
+  }
+});
+
+export const prelaunchAcquisitionListResponseSchema = z.object({
+  contractVersion: z.literal(PRELAUNCH_ACQUISITION_CONTRACT_VERSION),
+  leads: z.array(prelaunchAcquisitionLeadSchema).max(100),
+  nextCursor: acquisitionOpaqueRefSchema.nullable(),
+}).strict();
+
+export const prelaunchAcquisitionDetailResponseSchema = z.object({
+  contractVersion: z.literal(PRELAUNCH_ACQUISITION_CONTRACT_VERSION),
+  lead: prelaunchAcquisitionLeadSchema,
+}).strict();
+
+export type PrelaunchAcquisitionListRequest = z.infer<typeof prelaunchAcquisitionListRequestSchema>;
+export type PrelaunchAcquisitionDetailRequest = z.infer<typeof prelaunchAcquisitionDetailRequestSchema>;
+export type PrelaunchAcquisitionLead = z.infer<typeof prelaunchAcquisitionLeadSchema>;
+export type PrelaunchAcquisitionListResponse = z.infer<typeof prelaunchAcquisitionListResponseSchema>;
+export type PrelaunchAcquisitionDetailResponse = z.infer<typeof prelaunchAcquisitionDetailResponseSchema>;

package/src/marketing/seo/jsonLd.ts

@@ -0,0 +1,153 @@
+import type { OrganizationFacts } from "../contracts/contactLegal.js";
+
+export type JsonLdNode = Record<string, unknown> & { "@context"?: string; "@id"?: string };
+
+export function jsonLdGraph(...nodes: JsonLdNode[]) {
+  const seen = new Set<string>();
+  const graph = nodes.flatMap(({ "@context": _context, ...node }) => {
+    if (node["@id"] && seen.has(node["@id"] as string)) return [];
+    if (node["@id"]) seen.add(node["@id"] as string);
+    return [node];
+  });
+  return { "@context": "https://schema.org", "@graph": graph };
+}
+
+export function entityIds(origin: string) {
+  const site = origin.replace(/\/$/, "");
+  return {
+    organization: `${site}/#organization`,
+    website: `${site}/#website`,
+    brand: `${site}/#brand`,
+  };
+}
+
+export function organizationLd(origin: string, type: "Organization" | "OnlineStore", facts: OrganizationFacts) {
+  return {
+    "@context": "https://schema.org",
+    "@id": entityIds(origin).organization,
+    "@type": type,
+    name: facts.name,
+    legalName: facts.legalName,
+    url: facts.url,
+    logo: {
+      "@type": "ImageObject",
+      url: facts.logo.url,
+      contentUrl: facts.logo.contentUrl,
+      width: facts.logo.width,
+      height: facts.logo.height,
+    },
+    email: facts.email,
+    vatID: facts.vatID,
+    taxID: facts.taxID,
+    areaServed: facts.areaServed,
+    sameAs: facts.sameAs,
+    contactPoint: {
+      "@type": "ContactPoint",
+      email: facts.contactPoint.email,
+      contactType: facts.contactPoint.contactType,
+      availableLanguage: facts.contactPoint.availableLanguage,
+    },
+    address: {
+      "@type": "PostalAddress",
+      streetAddress: facts.address.streetAddress,
+      addressLocality: facts.address.addressLocality,
+      postalCode: facts.address.postalCode,
+      addressRegion: facts.address.addressRegion,
+      addressCountry: facts.address.addressCountry,
+    },
+  };
+}
+
+export function brandLd(origin: string, name: string, url: string) {
+  return { "@context": "https://schema.org", "@id": entityIds(origin).brand, "@type": "Brand", name, url };
+}
+
+export function websiteLd(origin: string, name: string, url: string, inLanguage: string[]) {
+  return {
+    "@context": "https://schema.org",
+    "@id": entityIds(origin).website,
+    "@type": "WebSite",
+    name,
+    url,
+    inLanguage,
+    publisher: { "@id": entityIds(origin).organization },
+  };
+}
+
+export function contactPageLd(origin: string, pageUrl: string) {
+  return {
+    "@context": "https://schema.org",
+    "@id": `${pageUrl.replace(/\/$/, "")}#webpage`,
+    "@type": "ContactPage",
+    url: pageUrl,
+    publisher: { "@id": entityIds(origin).organization },
+    mainEntity: { "@id": entityIds(origin).organization },
+  };
+}
+
+export interface NetContent { unscaled: number; scale: number; unit: string }
+
+export function schemaWeight(netContent: NetContent) {
+  const { unscaled, scale, unit } = netContent;
+  const unitCode = unit === "GRAM" || unit === "G" ? "GRM" : unit;
+  return { "@type": "QuantitativeValue", value: unscaled / 10 ** scale, unitCode };
+}
+
+export interface ProductFacts {
+  url: string;
+  name: string;
+  inLanguage: string;
+  brandName: string;
+  category?: string;
+  images: string[];
+  sku?: string;
+  gtin13?: string;
+  netContent?: NetContent;
+}
+
+export function productLd(origin: string, product: ProductFacts) {
+  return {
+    "@context": "https://schema.org",
+    "@id": `${product.url.replace(/\/$/, "")}#product`,
+    "@type": "Product",
+    name: product.name,
+    inLanguage: product.inLanguage,
+    brand: { "@id": entityIds(origin).brand, "@type": "Brand", name: product.brandName },
+    manufacturer: { "@id": entityIds(origin).organization },
+    ...(product.category !== undefined ? { category: product.category } : {}),
+    image: product.images,
+    ...(product.sku !== undefined ? { sku: product.sku } : {}),
+    ...(product.gtin13 !== undefined ? { gtin13: product.gtin13 } : {}),
+    ...(product.netContent ? { weight: schemaWeight(product.netContent) } : {}),
+    url: product.url,
+  };
+}
+
+const pageEntityId = (pageUrl: string, fragment: string) => `${pageUrl.replace(/\/$/, "")}#${fragment}`;
+
+export function faqPageLd(faqs: { question: string; answer: string }[], pageUrl: string) {
+  return {
+    "@context": "https://schema.org",
+    "@id": pageEntityId(pageUrl, "faq"),
+    "@type": "FAQPage",
+    mainEntity: faqs.map((faq) => ({
+      "@type": "Question",
+      name: faq.question,
+      acceptedAnswer: { "@type": "Answer", text: faq.answer },
+    })),
+  };
+}
+
+export function breadcrumbLd(items: { name: string; url?: string }[], pageUrl: string) {
+  return {
+    "@context": "https://schema.org",
+    "@id": pageEntityId(pageUrl, "breadcrumb"),
+    "@type": "BreadcrumbList",
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      ...(item.url ? { item: item.url } : {}),
+    })),
+  };
+}