@wildo-ai/saas-website 1.1.4 → 1.1.6

package/src/schemas/structured-data/pricing-offer-structured-data.shared.ts

@@ -0,0 +1,144 @@
+import {
+  ProductAvailability,
+  ProductPriceDisclosure,
+  PublicPricingAmountBasis,
+  PublicPricingRecurrenceUnit,
+  publicPricingAmountDecimal,
+  type PublicPricingCatalog,
+  type PublicPricingPlan,
+  type PublicPricingPrice,
+} from '@wildo-ai/saas-models/public-runtime';
+
+import type { WebsiteStructuredDataPayload } from './website-structured-data.shared.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.pricing-offer-structured-data facet:layer:core facet:family:website facet:audience:app-developer
+ *
+ * `buildWebsitePricingOfferStructuredData` — the `AggregateOffer` a pricing page publishes, DERIVED from
+ * the application's public pricing catalogue (#1835) instead of typed by hand beside it.
+ *
+ * ## What it publishes, and what it refuses to
+ *
+ * A search engine shows an offer's `price` as the price of the offer, so an offer is published only
+ * when that is TRUE:
+ *
+ * - the plan is on sale (`availability: AVAILABLE`) — an upcoming plan cannot be bought;
+ * - its price is `LISTED` — a starting price is a floor, and an on-request plan has no price;
+ * - its published price states the whole offer for its unit: a flat or per-unit amount, never an
+ *   indicative amount of a tiered, graduated or package price.
+ *
+ * Each published offer uses the plan's DEFAULT price (the one the catalogue marks) and carries a
+ * `UnitPriceSpecification` saying what the number is FOR: its recurrence as `billingDuration` (ISO 8601
+ * `P1M` / `P1Y`) and, for a per-unit price, a `referenceQuantity` of one of the page's unit (`member`)
+ * — so "$4 per member per month" is never read as "$4".
+ *
+ * One `AggregateOffer` per (currency, amount basis, recurrence): a range is only meaningful over prices
+ * that measure the same thing, so a flat price and a per-member price, or a monthly and a yearly one, are
+ * never folded into one `lowPrice` / `highPrice`. EVERY group's `@id` is `aggregateOfferIdPrefix` suffixed with
+ * what distinguishes it (`-per-unit-1-month-usd`), so an aggregate's identity depends only on what it
+ * aggregates: adding, removing or reordering a plan in ANOTHER group never moves it. Returns `[]` when
+ * nothing may be published — a page with only on-request plans publishes no price at all, which is the
+ * true statement.
+ */
+export interface BuildWebsitePricingOfferStructuredDataInput {
+  readonly catalog: PublicPricingCatalog;
+  /** The `@id` of the entity the offers price — typically the page's `SoftwareApplication`. */
+  readonly itemOfferedId: string;
+  /**
+   * The prefix of every `AggregateOffer` `@id` (`https://…/pricing#plans`); each group appends what it
+   * aggregates, e.g. `#plans-flat-1-month-usd`.
+   */
+  readonly aggregateOfferIdPrefix: string;
+  /** The URL of the page the offers are made on; each offer's URL is this plus `#plan-<key>`. */
+  readonly url: string;
+  /**
+   * The plan's name in the page's locale. Names are text a person reads, so they come from the page's
+   * label pack; a plan the callback does not name is published without one rather than with its key.
+   */
+  readonly planName?: (planKey: string) => string | undefined;
+  /**
+   * What ONE unit of a per-unit price is, in the page's locale (`member`, `seat`) — published as the
+   * offer's `referenceQuantity.unitText`. Required when any published offer is per-unit: omitting it
+   * would state a per-member price as a whole price, so the builder refuses instead.
+   */
+  readonly perUnitName?: string;
+}
+
+export function buildWebsitePricingOfferStructuredData(input: BuildWebsitePricingOfferStructuredDataInput): readonly WebsiteStructuredDataPayload[] {
+  const published = input.catalog.plans.flatMap((plan) => {
+    const price = publishablePrice(plan);
+    return price === undefined ? [] : [{ plan, price }];
+  });
+  if (published.some(({ price }) => price.amountBasis === PublicPricingAmountBasis.PER_UNIT) && !input.perUnitName) {
+    throw new Error(
+      '[buildWebsitePricingOfferStructuredData] a published plan is priced per unit, so the page must name the unit '
+        + '(`perUnitName`, e.g. "member"); without it the offer would state a per-unit price as the whole price.',
+    );
+  }
+  const groupKeyOf = (price: PublicPricingPrice): string =>
+    `${price.currency}|${price.amountBasis}|${price.recurrence.unit}|${price.recurrence.count}`;
+  const groupKeys = [...new Set(published.map(({ price }) => groupKeyOf(price)))];
+  return groupKeys.map((groupKey) => {
+    const offers = published.filter(({ price }) => groupKeyOf(price) === groupKey);
+    const sample = offers[0]!.price;
+    const amounts = offers.map(({ price }) => publicPricingAmountDecimal(price));
+    const numeric = amounts.map(Number);
+    return {
+      '@type': 'AggregateOffer',
+      '@id': `${input.aggregateOfferIdPrefix}-${aggregateSuffix(sample)}`,
+      itemOffered: { '@id': input.itemOfferedId },
+      priceCurrency: sample.currency,
+      lowPrice: amounts[numeric.indexOf(Math.min(...numeric))],
+      highPrice: amounts[numeric.indexOf(Math.max(...numeric))],
+      offerCount: offers.length,
+      url: input.url,
+      offers: offers.map(({ plan, price }) => {
+        const name = input.planName?.(plan.key);
+        const amount = publicPricingAmountDecimal(price);
+        return {
+          '@type': 'Offer',
+          ...(name === undefined ? {} : { name }),
+          price: amount,
+          priceCurrency: price.currency,
+          availability: 'https://schema.org/InStock',
+          url: `${input.url}#plan-${plan.key}`,
+          priceSpecification: {
+            '@type': 'UnitPriceSpecification',
+            price: amount,
+            priceCurrency: price.currency,
+            ...(price.recurrence.unit === PublicPricingRecurrenceUnit.ONE_TIME ? {} : { billingDuration: isoDurationOf(price) }),
+            ...(price.amountBasis === PublicPricingAmountBasis.PER_UNIT
+              ? { referenceQuantity: { '@type': 'QuantitativeValue', value: 1, unitText: input.perUnitName } }
+              : {}),
+          },
+        };
+      }),
+    };
+  });
+}
+
+/** What distinguishes an aggregate's `@id`: its basis, its recurrence and its currency — exactly its group key. */
+function aggregateSuffix(price: PublicPricingPrice): string {
+  return `${price.amountBasis}-${price.recurrence.count}-${price.recurrence.unit}-${price.currency}`.toLowerCase().replace(/_/gu, '-');
+}
+
+/** The plan's default price, when publishing it as the offer's price would be true. */
+function publishablePrice(plan: PublicPricingPlan): PublicPricingPrice | undefined {
+  if (plan.availability !== ProductAvailability.AVAILABLE) return undefined;
+  if (plan.priceDisclosure !== ProductPriceDisclosure.LISTED) return undefined;
+  const price = plan.prices.find((candidate) => candidate.isDefault) ?? plan.prices[0];
+  if (price === undefined || price.amountBasis === PublicPricingAmountBasis.VARIABLE) return undefined;
+  return price;
+}
+
+/** Total over the recurring units: a member added to the vocabulary is a compile error here until it is mapped. */
+const ISO_DURATION_DESIGNATOR: Record<Exclude<PublicPricingRecurrenceUnit, PublicPricingRecurrenceUnit.ONE_TIME>, string> = {
+  [PublicPricingRecurrenceUnit.MONTH]: 'M',
+  [PublicPricingRecurrenceUnit.YEAR]: 'Y',
+};
+
+function isoDurationOf(price: PublicPricingPrice): string {
+  const unit = price.recurrence.unit as Exclude<PublicPricingRecurrenceUnit, PublicPricingRecurrenceUnit.ONE_TIME>;
+  return `P${price.recurrence.count}${ISO_DURATION_DESIGNATOR[unit]}`;
+}
+/** @wildo_source:part:end saas.website.pricing-offer-structured-data */

package/src/schemas/structured-data/structured-data-reconciliation.shared.ts

@@ -103,6 +103,28 @@ export type StructuredDataReconciliationFinding =
   | StructuredDataDeprecatedFieldFinding
   | StructuredDataCrossEntityReferenceDriftFinding;
 
+/**
+ * An OPTIONAL field a payload leaves out, reported because its catalog entry opted in with
+ * `recommendOptionals: true` — the entry's statement that for this type the optional fields are
+ * where the richer search and answer-engine results come from.
+ *
+ * Deliberately NOT a finding. A finding says the payload is wrong (a missing required field, an
+ * unknown type, a deprecated field) and `--strict` escalates every finding to a failure. A payload
+ * without its optional fields is valid; reporting it through the same channel would fail strict CI for
+ * following the vocabulary. So recommendations travel beside the findings, are shown as information,
+ * and never change an audit's outcome.
+ */
+export interface StructuredDataOptionalFieldRecommendation {
+  pageRef: string;
+  routePath: string;
+  sectionRef: string;
+  entityType: string;
+  entityId?: string;
+  /** The entry's optional fields this payload does not carry, in catalog order. */
+  missingOptionalFields: readonly string[];
+  message: string;
+}
+
 export interface StructuredDataReconciliationPageResult {
   pageRef: string;
   routePath: string;
@@ -112,6 +134,8 @@ export interface StructuredDataReconciliationPageResult {
 
 export interface StructuredDataReconciliationResult {
   findings: StructuredDataReconciliationFinding[];
+  /** Optional-field recommendations from entries that opted in — information, never a finding. */
+  recommendations: StructuredDataOptionalFieldRecommendation[];
   pages: StructuredDataReconciliationPageResult[];
 }
 
@@ -133,6 +157,7 @@ export function reconcileStructuredDataAgainstCatalog(
   options: ReconcileStructuredDataOptions,
 ): StructuredDataReconciliationResult {
   const findings: StructuredDataReconciliationFinding[] = [];
+  const recommendations: StructuredDataOptionalFieldRecommendation[] = [];
   const pages: StructuredDataReconciliationPageResult[] = [];
   const sectionsByRef = new Map(
     options.sections.map((section) => [section.sectionRef, section] as const),
@@ -301,7 +326,7 @@ export function reconcileStructuredDataAgainstCatalog(
 
       const routeFindingStart = findings.length;
       for (const payloadContext of payloadContexts) {
-        validatePayloadAgainstCatalog(payloadContext, catalogByType, declaredEntityIds, findings);
+        validatePayloadAgainstCatalog(payloadContext, catalogByType, declaredEntityIds, findings, recommendations);
       }
 
       pages.push({
@@ -332,6 +357,7 @@ export function reconcileStructuredDataAgainstCatalog(
 
   return {
     findings,
+    recommendations,
     pages,
   };
 }
@@ -411,6 +437,7 @@ function validatePayloadAgainstCatalog(
   catalogByType: ReadonlyMap<string, StructuredDataCatalogEntry>,
   declaredEntityIds: ReadonlySet<string>,
   findings: StructuredDataReconciliationFinding[],
+  recommendations: StructuredDataOptionalFieldRecommendation[],
 ): void {
   const { payload, pageRef, routePath, sectionRef } = payloadContext;
   const entityType = payload['@type'];
@@ -450,6 +477,24 @@ function validatePayloadAgainstCatalog(
     }
   }
 
+  if (catalogEntry.recommendOptionals === true) {
+    const missingOptionalFields = (catalogEntry.optionalFields ?? []).filter((field) => !hasPresentFieldValue(payload, field));
+    if (missingOptionalFields.length > 0) {
+      recommendations.push({
+        pageRef,
+        routePath,
+        sectionRef,
+        entityType,
+        entityId,
+        missingOptionalFields,
+        message:
+          `Structured-data payload @type="${entityType}" emitted by section "${sectionRef}" on page "${pageRef}" ` +
+          `could carry ${missingOptionalFields.map((field) => `"${field}"`).join(', ')} — optional, and the catalog ` +
+          'recommends them for richer search and answer-engine results.',
+      });
+    }
+  }
+
   for (const deprecatedField of catalogEntry.deprecatedFields ?? []) {
     if (!hasPresentFieldValue(payload, deprecatedField.field)) {
       continue;

package/src/schemas/structured-data/website-structured-data.shared.schemas.ts

@@ -16,11 +16,13 @@
  *
  * - `@type` REQUIRED — the Schema.org entity kind (`'Article'`,
  *   `'BlogPosting'`, `'FAQPage'`, …). Typed as a free-form `string`
- *   here (not a closed enum) so app-side catalog extensions
- *   (e.g. `'SoftwareApplication'`, custom Schema.org-extension
- *   `@type`s) are emittable without a saas-website release. The
- *   companion's catalog reconciliation surface validates the
- *   `@type` value against the merged engine + app catalog.
+ *   here (not a closed enum) because this package ships to the browser
+ *   and must not carry the catalog: the renderer emits whatever type a
+ *   section returns. What VALIDATES the type is the Schema.org catalog,
+ *   through `wildo website audit` and the companion's reconciliation —
+ *   and that catalog is a closed enum an application can override but
+ *   not extend, so a type outside it reports `catalog-miss` until the
+ *   framework adds it.
  * - `@id?` OPTIONAL — a stable URI identifying the entity. Used for
  *   cross-referencing on the same page (e.g. `Article.publisher`
  *   referencing the page-level `Organization` via `@id`). The

package/dist/esm/core/external-providers/provider-scripts.website.d.ts

@@ -1,68 +0,0 @@
-/**
- * Loading what a website provider actually declared, instead of naming it.
- *
- * `FRONTEND_SDK` was a label on this surface. The layout resolved the analytics,
- * error-monitoring and captcha provider refs and stamped them into `data-*`
- * attributes on the page root; no consumer loaded anything. A provider could be
- * declared, enabled, hydrated — and do nothing at all.
- *
- * This is the consumer for the DATA half of a provider's executable surface: the
- * `scripts` it declares (#332). It serves the case a dynamic `import()` cannot,
- * and it is the dominant case on a marketing site: a vendor that ships a
- * global-installing `<script>` tag rather than an npm module (reCAPTCHA, tag
- * managers, chat widgets, and the CDN distributions of most analytics SDKs).
- *
- * The npm half — `sdk.activate`, a dynamic import inside the provider package —
- * needs the CODE channel, which needs this package to depend on
- * `@wildo-ai/external-connectors-public`. That dependency is not added here; see
- * the note in the S4a ledger. Nothing below anticipates it: a provider that
- * declares both gets its scripts from here and its SDK from there.
- *
- * ## Client-side injection, and the alternative that was rejected
- *
- * This is an Astro static site, so the "obvious" home for a third-party tag is
- * the built HTML `<head>`. That was rejected for now: the set of live providers
- * is per SERVICE and per ENVIRONMENT, resolved from the materialized artifact,
- * while the built HTML is one artifact shared across deploys of the same build.
- * Baking the tags in would make the build environment-specific — the same class
- * of coupling the DATA channel exists to avoid. Injecting from the client keeps
- * one build correct everywhere, at the cost of the tag arriving after hydration.
- * Revisit if a provider ever needs to run before first paint.
- */
-import type { ProviderFrontendScriptDeclaration } from '@wildo-ai/saas-models/public-runtime';
-import type { FrontendWebsiteProviderRegistry } from './frontend-provider-registry.website';
-/**
- * Marks a `<script>` this module owns, so a re-render, a client-side route
- * change or a second layout mount finds it instead of appending a duplicate.
- * A vendor tag loaded twice initialises twice — two analytics clients, two sets
- * of events — which is the failure mode this attribute exists to prevent.
- */
-export declare const PROVIDER_SCRIPT_MARKER_ATTRIBUTE = "data-wildo-provider-script";
-export interface DeclaredProviderScript {
-    readonly providerRef: string;
-    readonly declaration: ProviderFrontendScriptDeclaration;
-}
-/**
- * Every script declared by the providers live on this surface, in registry
- * order, with the declaring ref kept beside each one so a failure can name it.
- */
-export declare function collectDeclaredProviderScripts(registry: FrontendWebsiteProviderRegistry | undefined): ReadonlyArray<DeclaredProviderScript>;
-export interface InjectProviderScriptsResult {
-    /** Refs whose script this call added. */
-    readonly injected: ReadonlyArray<string>;
-    /** Refs whose script was already present, so nothing was added. */
-    readonly alreadyPresent: ReadonlyArray<string>;
-}
-/**
- * Adds each declared script to the document, once.
- *
- * Idempotent by `src`: a declaration whose element is already in the document is
- * skipped. Callers may therefore run this on every mount without tracking state.
- *
- * `async` defaults to TRUE when the declaration says nothing. A third-party tag
- * that blocks parsing is the single most common way an analytics provider costs
- * a marketing site its paint metrics, and a provider author who has not thought
- * about it should get the safe answer rather than the blocking one.
- */
-export declare function injectProviderScripts(scripts: ReadonlyArray<DeclaredProviderScript>, targetDocument: Document): InjectProviderScriptsResult;
-//# sourceMappingURL=provider-scripts.website.d.ts.map

package/dist/esm/core/external-providers/provider-scripts.website.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-scripts.website.d.ts","sourceRoot":"","sources":["../../../../src/core/external-providers/provider-scripts.website.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,sCAAsC,CAAC;AAC9F,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,sCAAsC,CAAC;AAE5F;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,+BAA+B,CAAC;AAE7E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,iCAAiC,CAAC;CACzD;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,+BAA+B,GAAG,SAAS,GACpD,aAAa,CAAC,sBAAsB,CAAC,CAUvC;AAED,MAAM,WAAW,2BAA2B;IAC1C,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,CAAC,sBAAsB,CAAC,EAC9C,cAAc,EAAE,QAAQ,GACvB,2BAA2B,CAsC7B"}

package/dist/esm/core/external-providers/provider-scripts.website.js

@@ -1,99 +0,0 @@
-/**
- * Loading what a website provider actually declared, instead of naming it.
- *
- * `FRONTEND_SDK` was a label on this surface. The layout resolved the analytics,
- * error-monitoring and captcha provider refs and stamped them into `data-*`
- * attributes on the page root; no consumer loaded anything. A provider could be
- * declared, enabled, hydrated — and do nothing at all.
- *
- * This is the consumer for the DATA half of a provider's executable surface: the
- * `scripts` it declares (#332). It serves the case a dynamic `import()` cannot,
- * and it is the dominant case on a marketing site: a vendor that ships a
- * global-installing `<script>` tag rather than an npm module (reCAPTCHA, tag
- * managers, chat widgets, and the CDN distributions of most analytics SDKs).
- *
- * The npm half — `sdk.activate`, a dynamic import inside the provider package —
- * needs the CODE channel, which needs this package to depend on
- * `@wildo-ai/external-connectors-public`. That dependency is not added here; see
- * the note in the S4a ledger. Nothing below anticipates it: a provider that
- * declares both gets its scripts from here and its SDK from there.
- *
- * ## Client-side injection, and the alternative that was rejected
- *
- * This is an Astro static site, so the "obvious" home for a third-party tag is
- * the built HTML `<head>`. That was rejected for now: the set of live providers
- * is per SERVICE and per ENVIRONMENT, resolved from the materialized artifact,
- * while the built HTML is one artifact shared across deploys of the same build.
- * Baking the tags in would make the build environment-specific — the same class
- * of coupling the DATA channel exists to avoid. Injecting from the client keeps
- * one build correct everywhere, at the cost of the tag arriving after hydration.
- * Revisit if a provider ever needs to run before first paint.
- */
-/**
- * Marks a `<script>` this module owns, so a re-render, a client-side route
- * change or a second layout mount finds it instead of appending a duplicate.
- * A vendor tag loaded twice initialises twice — two analytics clients, two sets
- * of events — which is the failure mode this attribute exists to prevent.
- */
-export const PROVIDER_SCRIPT_MARKER_ATTRIBUTE = 'data-wildo-provider-script';
-/**
- * Every script declared by the providers live on this surface, in registry
- * order, with the declaring ref kept beside each one so a failure can name it.
- */
-export function collectDeclaredProviderScripts(registry) {
-    if (registry === undefined)
-        return [];
-    const collected = [];
-    for (const provider of registry.modules.values()) {
-        for (const declaration of provider.scripts ?? []) {
-            collected.push({ providerRef: provider.metadata.ref, declaration });
-        }
-    }
-    return collected;
-}
-/**
- * Adds each declared script to the document, once.
- *
- * Idempotent by `src`: a declaration whose element is already in the document is
- * skipped. Callers may therefore run this on every mount without tracking state.
- *
- * `async` defaults to TRUE when the declaration says nothing. A third-party tag
- * that blocks parsing is the single most common way an analytics provider costs
- * a marketing site its paint metrics, and a provider author who has not thought
- * about it should get the safe answer rather than the blocking one.
- */
-export function injectProviderScripts(scripts, targetDocument) {
-    const injected = [];
-    const alreadyPresent = [];
-    for (const { providerRef, declaration } of scripts) {
-        // Matched by reading the attribute rather than by a selector carrying the
-        // URL: a `src` can contain characters a CSS selector would have to escape,
-        // and an escaping bug here would show up as a duplicated vendor tag — two
-        // analytics clients, two sets of events — rather than as an error.
-        const existing = [
-            ...targetDocument.querySelectorAll(`script[${PROVIDER_SCRIPT_MARKER_ATTRIBUTE}]`),
-        ].some((element) => element.getAttribute('src') === declaration.src);
-        if (existing) {
-            alreadyPresent.push(providerRef);
-            continue;
-        }
-        const element = targetDocument.createElement('script');
-        element.src = declaration.src;
-        element.setAttribute(PROVIDER_SCRIPT_MARKER_ATTRIBUTE, providerRef);
-        if (declaration.integrity !== undefined) {
-            element.integrity = declaration.integrity;
-        }
-        if (declaration.crossOrigin !== undefined) {
-            element.crossOrigin = declaration.crossOrigin;
-        }
-        // Both flags are set explicitly rather than left to the element's defaults:
-        // a dynamically created script is `async` by default, so `defer: true` alone
-        // would be silently ignored without the paired `async = false`.
-        element.async = declaration.async ?? declaration.defer !== true;
-        element.defer = declaration.defer ?? false;
-        targetDocument.head.appendChild(element);
-        injected.push(providerRef);
-    }
-    return { injected, alreadyPresent };
-}
-//# sourceMappingURL=provider-scripts.website.js.map

package/dist/esm/core/external-providers/provider-scripts.website.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-scripts.website.js","sourceRoot":"","sources":["../../../../src/core/external-providers/provider-scripts.website.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,4BAA4B,CAAC;AAO7E;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAqD;IAErD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAEtC,MAAM,SAAS,GAA6B,EAAE,CAAC;IAC/C,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACjD,KAAK,MAAM,WAAW,IAAI,QAAQ,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YACjD,SAAS,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,WAAW,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAA8C,EAC9C,cAAwB;IAExB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,KAAK,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,OAAO,EAAE,CAAC;QACnD,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,mEAAmE;QACnE,MAAM,QAAQ,GAAG;YACf,GAAG,cAAc,CAAC,gBAAgB,CAAC,UAAU,gCAAgC,GAAG,CAAC;SAClF,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,WAAW,CAAC,GAAG,CAAC,CAAC;QACrE,IAAI,QAAQ,EAAE,CAAC;YACb,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACjC,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QACvD,OAAO,CAAC,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC;QAC9B,OAAO,CAAC,YAAY,CAAC,gCAAgC,EAAE,WAAW,CAAC,CAAC;QAEpE,IAAI,WAAW,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACxC,OAAO,CAAC,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC;QAC5C,CAAC;QACD,IAAI,WAAW,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YAC1C,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC,WAAW,CAAC;QAChD,CAAC;QACD,4EAA4E;QAC5E,6EAA6E;QAC7E,gEAAgE;QAChE,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC,KAAK,IAAI,WAAW,CAAC,KAAK,KAAK,IAAI,CAAC;QAChE,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC,KAAK,IAAI,KAAK,CAAC;QAE3C,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACzC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;AACtC,CAAC","sourcesContent":["/**\n * Loading what a website provider actually declared, instead of naming it.\n *\n * `FRONTEND_SDK` was a label on this surface. The layout resolved the analytics,\n * error-monitoring and captcha provider refs and stamped them into `data-*`\n * attributes on the page root; no consumer loaded anything. A provider could be\n * declared, enabled, hydrated — and do nothing at all.\n *\n * This is the consumer for the DATA half of a provider's executable surface: the\n * `scripts` it declares (#332). It serves the case a dynamic `import()` cannot,\n * and it is the dominant case on a marketing site: a vendor that ships a\n * global-installing `<script>` tag rather than an npm module (reCAPTCHA, tag\n * managers, chat widgets, and the CDN distributions of most analytics SDKs).\n *\n * The npm half — `sdk.activate`, a dynamic import inside the provider package —\n * needs the CODE channel, which needs this package to depend on\n * `@wildo-ai/external-connectors-public`. That dependency is not added here; see\n * the note in the S4a ledger. Nothing below anticipates it: a provider that\n * declares both gets its scripts from here and its SDK from there.\n *\n * ## Client-side injection, and the alternative that was rejected\n *\n * This is an Astro static site, so the \"obvious\" home for a third-party tag is\n * the built HTML `<head>`. That was rejected for now: the set of live providers\n * is per SERVICE and per ENVIRONMENT, resolved from the materialized artifact,\n * while the built HTML is one artifact shared across deploys of the same build.\n * Baking the tags in would make the build environment-specific — the same class\n * of coupling the DATA channel exists to avoid. Injecting from the client keeps\n * one build correct everywhere, at the cost of the tag arriving after hydration.\n * Revisit if a provider ever needs to run before first paint.\n */\n\nimport type { ProviderFrontendScriptDeclaration } from '@wildo-ai/saas-models/public-runtime';\nimport type { FrontendWebsiteProviderRegistry } from './frontend-provider-registry.website';\n\n/**\n * Marks a `<script>` this module owns, so a re-render, a client-side route\n * change or a second layout mount finds it instead of appending a duplicate.\n * A vendor tag loaded twice initialises twice — two analytics clients, two sets\n * of events — which is the failure mode this attribute exists to prevent.\n */\nexport const PROVIDER_SCRIPT_MARKER_ATTRIBUTE = 'data-wildo-provider-script';\n\nexport interface DeclaredProviderScript {\n  readonly providerRef: string;\n  readonly declaration: ProviderFrontendScriptDeclaration;\n}\n\n/**\n * Every script declared by the providers live on this surface, in registry\n * order, with the declaring ref kept beside each one so a failure can name it.\n */\nexport function collectDeclaredProviderScripts(\n  registry: FrontendWebsiteProviderRegistry | undefined,\n): ReadonlyArray<DeclaredProviderScript> {\n  if (registry === undefined) return [];\n\n  const collected: DeclaredProviderScript[] = [];\n  for (const provider of registry.modules.values()) {\n    for (const declaration of provider.scripts ?? []) {\n      collected.push({ providerRef: provider.metadata.ref, declaration });\n    }\n  }\n  return collected;\n}\n\nexport interface InjectProviderScriptsResult {\n  /** Refs whose script this call added. */\n  readonly injected: ReadonlyArray<string>;\n  /** Refs whose script was already present, so nothing was added. */\n  readonly alreadyPresent: ReadonlyArray<string>;\n}\n\n/**\n * Adds each declared script to the document, once.\n *\n * Idempotent by `src`: a declaration whose element is already in the document is\n * skipped. Callers may therefore run this on every mount without tracking state.\n *\n * `async` defaults to TRUE when the declaration says nothing. A third-party tag\n * that blocks parsing is the single most common way an analytics provider costs\n * a marketing site its paint metrics, and a provider author who has not thought\n * about it should get the safe answer rather than the blocking one.\n */\nexport function injectProviderScripts(\n  scripts: ReadonlyArray<DeclaredProviderScript>,\n  targetDocument: Document,\n): InjectProviderScriptsResult {\n  const injected: string[] = [];\n  const alreadyPresent: string[] = [];\n\n  for (const { providerRef, declaration } of scripts) {\n    // Matched by reading the attribute rather than by a selector carrying the\n    // URL: a `src` can contain characters a CSS selector would have to escape,\n    // and an escaping bug here would show up as a duplicated vendor tag — two\n    // analytics clients, two sets of events — rather than as an error.\n    const existing = [\n      ...targetDocument.querySelectorAll(`script[${PROVIDER_SCRIPT_MARKER_ATTRIBUTE}]`),\n    ].some((element) => element.getAttribute('src') === declaration.src);\n    if (existing) {\n      alreadyPresent.push(providerRef);\n      continue;\n    }\n\n    const element = targetDocument.createElement('script');\n    element.src = declaration.src;\n    element.setAttribute(PROVIDER_SCRIPT_MARKER_ATTRIBUTE, providerRef);\n\n    if (declaration.integrity !== undefined) {\n      element.integrity = declaration.integrity;\n    }\n    if (declaration.crossOrigin !== undefined) {\n      element.crossOrigin = declaration.crossOrigin;\n    }\n    // Both flags are set explicitly rather than left to the element's defaults:\n    // a dynamically created script is `async` by default, so `defer: true` alone\n    // would be silently ignored without the paired `async = false`.\n    element.async = declaration.async ?? declaration.defer !== true;\n    element.defer = declaration.defer ?? false;\n\n    targetDocument.head.appendChild(element);\n    injected.push(providerRef);\n  }\n\n  return { injected, alreadyPresent };\n}\n"]}

package/src/core/external-providers/__tests__/provider-scripts.website.test.ts

@@ -1,146 +0,0 @@
-import { beforeEach, describe, expect, it } from 'vitest';
-import {
-  ENGINE_PROVIDER_ORIGIN,
-  ProviderFrontendScriptCrossOrigin,
-  ProviderTier,
-  defineProviderMetadata,
-  type FrontendProvidersBlock,
-} from '@wildo-ai/saas-models/public-runtime';
-import { createFrontendWebsiteProviderRegistry } from '../frontend-provider-registry.website';
-import {
-  PROVIDER_SCRIPT_MARKER_ATTRIBUTE,
-  collectDeclaredProviderScripts,
-  injectProviderScripts,
-} from '../provider-scripts.website';
-
-function registryWith(scriptsByRef: Record<string, unknown[]>): ReturnType<typeof createFrontendWebsiteProviderRegistry> {
-  const providers = Object.fromEntries(
-    Object.entries(scriptsByRef).map(([ref, scripts]) => [
-      ref,
-      {
-        metadata: defineProviderMetadata({
-          ref,
-          packageName: `@wildo-ai/provider-${ref}`,
-          tier: ProviderTier.CATALOGUE,
-          origin: ENGINE_PROVIDER_ORIGIN,
-        }),
-        providerCapabilities: [],
-        protocols: ['FRONTEND_SDK'],
-        scripts,
-      },
-    ]),
-  );
-  return createFrontendWebsiteProviderRegistry({ entries: { providers } as unknown as FrontendProvidersBlock });
-}
-
-function injectedScripts(): HTMLScriptElement[] {
-  return [...document.querySelectorAll<HTMLScriptElement>(`script[${PROVIDER_SCRIPT_MARKER_ATTRIBUTE}]`)];
-}
-
-describe('website provider scripts', () => {
-  beforeEach(() => {
-    document.head.innerHTML = '';
-  });
-
-  it('collects every declared script with the ref that declared it', () => {
-    const collected = collectDeclaredProviderScripts(
-      registryWith({
-        analytics: [{ src: 'https://cdn.analytics.test/a.js' }],
-        captcha: [{ src: 'https://captcha.test/api.js' }, { src: 'https://captcha.test/extra.js' }],
-      }),
-    );
-
-    expect(collected.map((entry) => `${entry.providerRef}:${entry.declaration.src}`)).toEqual([
-      'analytics:https://cdn.analytics.test/a.js',
-      'captcha:https://captcha.test/api.js',
-      'captcha:https://captcha.test/extra.js',
-    ]);
-  });
-
-  it('collects nothing when no registry is hydrated at all', () => {
-    expect(collectDeclaredProviderScripts(undefined)).toEqual([]);
-  });
-
-  it('injects a declared script into the document head, carrying its SRI and crossorigin', () => {
-    const result = injectProviderScripts(
-      collectDeclaredProviderScripts(
-        registryWith({
-          analytics: [
-            {
-              src: 'https://cdn.analytics.test/a.js',
-              integrity: 'sha384-abc',
-              crossOrigin: ProviderFrontendScriptCrossOrigin.ANONYMOUS,
-            },
-          ],
-        }),
-      ),
-      document,
-    );
-
-    const [element] = injectedScripts();
-    expect(result.injected).toEqual(['analytics']);
-    expect(element.src).toBe('https://cdn.analytics.test/a.js');
-    expect(element.integrity).toBe('sha384-abc');
-    expect(element.crossOrigin).toBe('anonymous');
-    expect(element.getAttribute(PROVIDER_SCRIPT_MARKER_ATTRIBUTE)).toBe('analytics');
-  });
-
-  it('defaults to async, because a blocking third-party tag is how a marketing site loses its paint', () => {
-    injectProviderScripts(
-      collectDeclaredProviderScripts(registryWith({ analytics: [{ src: 'https://cdn.analytics.test/a.js' }] })),
-      document,
-    );
-
-    expect(injectedScripts()[0].async).toBe(true);
-    expect(injectedScripts()[0].defer).toBe(false);
-  });
-
-  it('honours defer by turning async OFF, which a dynamically created script does not do on its own', () => {
-    // A script element created by script is async by default, so `defer: true`
-    // alone would be silently ignored — the exact shape of a declaration that
-    // looks respected and is not.
-    injectProviderScripts(
-      collectDeclaredProviderScripts(
-        registryWith({ analytics: [{ src: 'https://cdn.analytics.test/a.js', defer: true }] }),
-      ),
-      document,
-    );
-
-    expect(injectedScripts()[0].async).toBe(false);
-    expect(injectedScripts()[0].defer).toBe(true);
-  });
-
-  it('is idempotent: a second call adds nothing, so a remount cannot start a vendor twice', () => {
-    const scripts = collectDeclaredProviderScripts(
-      registryWith({ analytics: [{ src: 'https://cdn.analytics.test/a.js' }] }),
-    );
-
-    injectProviderScripts(scripts, document);
-    const second = injectProviderScripts(scripts, document);
-
-    expect(injectedScripts()).toHaveLength(1);
-    expect(second.injected).toEqual([]);
-    expect(second.alreadyPresent).toEqual(['analytics']);
-  });
-
-  it('matches an existing script by its src even when the URL carries query characters', () => {
-    const scripts = collectDeclaredProviderScripts(
-      registryWith({ captcha: [{ src: 'https://captcha.test/api.js?render=abc&hl=fr' }] }),
-    );
-
-    injectProviderScripts(scripts, document);
-    injectProviderScripts(scripts, document);
-
-    expect(injectedScripts()).toHaveLength(1);
-  });
-
-  it('adds nothing for a provider that declares no scripts', () => {
-    const result = injectProviderScripts(
-      collectDeclaredProviderScripts(registryWith({ analytics: [] })),
-      document,
-    );
-
-    expect(result.injected).toEqual([]);
-    expect(injectedScripts()).toHaveLength(0);
-  });
-});