@reblu/site-next 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -0,0 +1,473 @@
+# @reblu/site-next
+
+## 1.8.0
+
+### Minor Changes
+
+- 984f8b5: Add `@reblu/site-next/academy`, exporting `AcademyEnrollmentForm` — a
+  copy-injectable, per-tenant customizable enrollment-request form — and
+  `deriveValidationFields`, a pure helper that derives its validation fields
+  from the course/config data a SITE's academy API already returns.
+
+## 1.7.1
+
+### Patch Changes
+
+- 9f54c58: REB-774 — ship `CHANGELOG.md` inside the published npm tarball for every
+  `@reblu/site-*` package (verified via `pnpm pack`: it was previously absent,
+  since `"files": ["dist"]` limited the tarball to `dist/` and npm only
+  auto-includes `README.md`, `LICENSE` and `package.json`). Consumers can now
+  read the changelog for the version they installed straight from
+  `node_modules/@reblu/<pkg>/CHANGELOG.md`.
+- Updated dependencies [9f54c58]
+- Updated dependencies [9f54c58]
+  - @reblu/site-contracts@1.0.1
+  - @reblu/site-client@5.0.1
+  - @reblu/site-ui@0.5.1
+
+## 1.7.0
+
+### Minor Changes
+
+- deda0c0: REB-762 / REB-763 — a user who asks for a new magic link is told the truth, once
+
+  Expired link → "Enlace caducado" → re-request from the form on that same page →
+  "enlace enviado" appears while "Enlace caducado" is still on screen, unchanged.
+  The expired notice is the more alarming of the two, so it is the one believed,
+  so the user requests again — within Supabase's 60-second per-user interval,
+  which drops the second link before any email is sent while our route answers a
+  cheerful 200. Nothing arrives, the screen still says expired, and round it goes.
+
+  Two changes close the loop:
+  - `AuthCallback` drops its verdict about the old link when a new one is
+    requested. `LoginForm` dispatches `reblu:magic-link-requested` on `window` and
+    the callback listens. This covers the whole class, not the reported case: an
+    expired link, an invalid one, an already-used one, and a failed exchange all
+    clear. The stale notice is REMOVED rather than dimmed — a greyed-out alarm is
+    still read as current.
+  - `LoginForm` holds its success panel for a 60-second cooldown with a visible
+    countdown, then offers "Pedir otro enlace". There is no submit button to press
+    during the window in which Supabase would silently drop the request. It leaks
+    nothing: the UI behaves identically for a real and a non-existent address.
+
+  Copy is now true in both branches. `magicLinkSuccessTitle` is "Revisa tu correo"
+  (was "¡Enlace enviado!") and `magicLinkSuccessMessage` no longer asserts a send
+  that may never have happened. base-api's `/api/site/auth/magic-link-request`
+  matches, in every branch including the deliberate silent 200 on our own IP
+  limiter — that silence stays, it is what stops a 429 from being an
+  account-existence oracle; only the lie is gone.
+
+  New public surface, all additive:
+  - `LoginForm` gains an optional `cooldownSeconds` prop and two copy keys,
+    `magicLinkCooldownMessage` (with a `{seconds}` placeholder) and
+    `magicLinkResendCta`. No existing prop changed shape. `AuthCallback`'s props
+    are untouched, so an already-published SITE page picks the fix up by
+    upgrading the package alone.
+  - `MAGIC_LINK_COOLDOWN_SECONDS`, `MAGIC_LINK_REQUESTED_EVENT`,
+    `emitMagicLinkRequested`, `onMagicLinkRequested`.
+
+  **Operators:** 60 is a MIRROR of the Supabase project's "minimum interval per
+  user", which we neither own nor can read at runtime — it is measured at 60 s on
+  the Dermamedicin project and set to 1 s on the local tenant stack, so the two
+  already differ by environment. It is declared once, in
+  `MAGIC_LINK_COOLDOWN_SECONDS`. If a project's interval changes, pass
+  `cooldownSeconds` for that SITE rather than adding a second literal.
+
+### Patch Changes
+
+- Updated dependencies [340db30]
+  - @reblu/site-contracts@1.0.0
+  - @reblu/site-client@5.0.0
+
+## 1.6.0
+
+### Minor Changes
+
+- 0e0a684: Add `@reblu/site-next/recaptcha` (REB-588) — the SITE's half of the contact-form captcha
+  contract, so no SITE re-implements Google's flow or verifies a token wrongly.
+
+  ## Why this exists
+
+  There were four copies of this flow. `apps/base-api` had one, `apps/demo-site` had another,
+  and the external `reblu-site-dermamedicin` repo had a third plus its own availability gate.
+  They had already drifted: one called `executeRecaptcha('submit_form')`, another
+  `'contact_form'`; one carried a retry loop and the others did not; one mounted the provider
+  eagerly, one on scroll, one on interaction. reCAPTCHA v3 scores **per action**, so two SITEs
+  naming the action differently are building two unrelated score histories for the same
+  feature — and a defect fixed in one copy stays live in the other three.
+
+  An external SITE repo could not share any of it. It can install `@reblu/site-*`; it cannot
+  import `apps/base-api/src/components/`, and `@reblu/ui` is `"private": true` so it is not
+  publishable and never will be the home for something an external SITE needs. The SDK is the
+  only place a decision like this gets made once.
+
+  ## What ships
+  - `RECAPTCHA_ACTION` — the one action name. `contact_form` over `submit_form` because it
+    names the form rather than the verb; a second protected form needs its own action, and
+    `submit_form` would have nothing left to call it. It buys comparable scores and nothing
+    more: base-api's `serverCaptchaVerify` checks only `success` and `score` and never reads
+    the `action` Google returns, so a token minted for another action verifies just as well.
+    Documented in place so nobody mistakes it for enforcement; binding it is a follow-up on
+    base-api.
+  - `resolveContactFormAvailability(analytics)` / `isContactFormAvailable(a)` — the render
+    gate, plus `ContactFormAvailability` and `ContactFormModeExhaustiveCheck`.
+  - `deferredRecaptchaKey(siteKey, armed)` — the interaction-mount key.
+  - `isSafeRecaptchaSiteKey` / `RECAPTCHA_SITE_KEY_PATTERN` — the site-key shape guard.
+
+  ## Which half lives where — the security split, stated
+
+  The **site key** is public by design: it travels to the browser inside the script URL, and
+  this module handles it. The **secret** never leaves base-api — it is stored per tenant in
+  `site_integration_config.recaptchaSecretKey` and read only by `serverCaptchaVerify` when
+  `POST /api/site/contact-form` runs.
+
+  **Nothing in this module, this package, or any `@reblu/site-*` package ever sees the secret
+  or calls Google's `siteverify`.** A SITE holding the secret would be a SITE that could be
+  tricked into approving its own tokens, and a distributable SDK is the worst possible place
+  to put a credential. The SITE mints a token and posts it as `ContactFormInput.captcha`;
+  base-api decides. That half already worked, and this changeset does not touch it.
+
+  ## The gate is an allow-list, and that is not a style preference
+
+  `resolveContactFormAvailability` accepts `DB_ONLY`, `WEBHOOK` and `RESEND`, never
+  `mode !== 'DISABLED'`. The deny-list version is a real incident: it rendered a form for
+  `NOT_CONFIGURED` too — which is what every freshly provisioned tenant carries until someone
+  finishes the wizard (REB-586) — so a visitor typed out a medical enquiry, pressed send, and
+  got `503 Contact form is disabled`. They learned the clinic could not be reached only after
+  writing to it, which is the worst possible order. An unknown mode, a mode from a base-api
+  newer than your SDK, and a config read that threw all resolve to the same answer: no form.
+  The page still shows the phone, the email and the address.
+
+  The key is checked for the same reason. `ContactFormInput.captcha` is required, so an
+  operational mode with no usable key is a form whose every submission is dead on arrival.
+  `missing-recaptcha-key` and `malformed-recaptcha-key` are separate reasons because they call
+  for different fixes by different people.
+
+  The list is a deliberate duplicate of base-api's `CONTACT_FORM_OPERATIONAL_MODES` — neither
+  side may import the other across that trust boundary. **This change does not delete the
+  existing copies**, so the list is now written three times: base-api's (authoritative), the
+  SDK's, and `apps/demo-site/src/lib/contact-form-mode.ts` (the reference SITE, not yet
+  migrated). All three are pinned by
+  `apps/base-api/tests/unit/lib/contracts/contact-form-mode-drift.test.ts`, on the same
+  pattern as REB-617's analytics-id guard: same members and same order for the two ordered
+  lists, same member set for demo-site's `Record`.
+
+  The type system does not cover this. The SDK's compile-time exhaustiveness check fires only
+  when the `ContactFormMode` union GAINS a member, and is blind to base-api NARROWING which
+  modes it accepts. Dropping `WEBHOOK` from base-api would otherwise leave every SITE
+  rendering a form base-api has stopped accepting — the REB-586 incident, reintroduced
+  through the back door. The SDK and base-api also now share one name for the concept; a
+  second name for one thing is how the extra copies got made in the first place.
+
+  ## The site-key guard, and its deliberate looseness
+
+  `recaptchaSiteKey` is the only tenant-controlled field on `/api/site/analytics` with **no
+  validation at any layer** — not the nexus form, not the route handler, not the response
+  contract. `gaId` and `clarityId` got all three in REB-617; this one was left behind. Its
+  severity is lower (the value lands in a script `src` query parameter, not an executing
+  script body, so it is not the same XSS sink), but the reliability hole is real: a mistyped
+  key renders a form that looks live and silently eats every enquiry.
+
+  So the SDK re-validates on read, exactly as `@reblu/site-next/analytics` already does for
+  the other two — base-api is not the only thing a SITE ever talks to. The pattern is a
+  **sink-safety** guard, not a guess at Google's key format: it excludes spaces, quotes,
+  newlines, `&` and `#`, and its length bounds (16–128) are far wider than the 40 characters
+  Google issues. A bound tight enough to be a real format check would be a bound tight enough
+  to take a working tenant offline the day Google changes its key length. The right place to
+  tighten is the nexus write path, where an owner can still see and fix the error.
+
+  ## Interaction-mount, verified against the vendor rather than asserted
+
+  `GoogleReCaptchaProvider` loads `api.js` the moment it mounts, so mounting it with the form
+  means every visitor who merely lands on the page to read the phone number has contacted
+  Google — on a clinic's contact page, a third-party request nobody asked for, on a route
+  whose whole subject is personal data.
+
+  `deferredRecaptchaKey` returns `''` until `armed`. An empty key mounts the provider and
+  injects nothing; swapping the real key in re-runs the library's effect and injects it then,
+  **without remounting the provider's children**, so the visitor does not lose focus or a
+  half-typed word at the instant the script arrives.
+
+  Both of those are claims about somebody else's code, and prose asserting them is worthless —
+  the library could inject eagerly in its next version and every comment here would quietly
+  become a lie while CI stayed green. So `tests/recaptcha-deferred-oracle.test.tsx` drives the
+  **real** `react-google-recaptcha-v3` and counts `<script>` tags in the DOM, including a
+  control proving a key supplied on the first render _does_ inject. If interaction-mount ever
+  stops working, that test goes red.
+
+  **This is not cookie consent.** Deferring the script narrows the exposure; it does not gate
+  it on a lawful basis. That remains REB-642, and this module says so where someone reaching
+  for it will read it.
+
+  ## Zero dependencies, and no `'use client'`
+
+  The subpath imports **nothing** — not React, not `next`, and notably not
+  `react-google-recaptcha-v3`, which stays the consuming SITE's dependency. It also carries no
+  `'use client'` directive, because the same functions run on both sides of the RSC boundary:
+  the server page resolves availability, the client component arms the key.
+
+  Both properties are gated by `tests/recaptcha-subpath-isolation.test.ts`, which runs a real
+  tsup build and asserts on the emitted bytes — the same enforcement `./cache` (REB-489),
+  `./json-ld` (REB-622) and `./analytics` (REB-617) already have.
+
+  ## Adoption
+
+  Additive — no existing export changes, nothing breaks. SITE repos replace their hand-written
+  availability check and provider wiring with `resolveContactFormAvailability` +
+  `deferredRecaptchaKey`, and switch `executeRecaptcha(...)` to `RECAPTCHA_ACTION`. Note that
+  switching the action re-baselines that SITE's reCAPTCHA score history, because Google charts
+  each action separately.
+
+  `apps/demo-site` is **not** migrated here — its form is a ~500-line hand-written component
+  built on `@reblu/ui` and its own schema, and folding that into this change would bury the
+  SDK surface in an unrelated refactor. Its `contact-form-mode.ts` is re-labelled instead: it
+  used to call itself "the template every external SITE repo copies", which this change makes
+  wrong, since it lacks the site-key check and its page gate only tests `!!recaptchaSiteKey`.
+  Migrating it is a follow-up.
+
+## 1.5.2
+
+### Patch Changes
+
+- Updated dependencies [65e124a]
+  - @reblu/site-ui@0.5.0
+
+## 1.5.1
+
+### Patch Changes
+
+- Updated dependencies [e5cda17]
+- Updated dependencies [7dcfb4f]
+  - @reblu/site-ui@0.4.0
+  - @reblu/site-contracts@0.5.0
+  - @reblu/site-client@4.0.0
+
+## 1.5.0
+
+### Minor Changes
+
+- 39ea223: Add `<AnalyticsScripts>` and the analytics id validators (`@reblu/site-next/analytics`)
+  — a safe renderer for tenant-configured Google Analytics and Microsoft Clarity tags.
+
+  Every SITE built on this SDK interpolated the tenant's analytics ids straight into
+  the body of an executing `<script>`:
+
+  ```js
+  gtag('config','${analytics.gaId}');
+  …"clarity","script","${analytics.clarityId}");
+  ```
+
+  No validation, no escaping, no sanitiser anywhere in the path. A `gaId` of
+  `x');alert(document.cookie);//` closes the string literal, closes the call,
+  comments out the remainder, and runs arbitrary JS on the tenant's OWN ORIGIN — on
+  every page including checkout, same origin as the portal session cookie. That is
+  the same trust boundary REB-613 closed on the sink next door (nexus-authored HTML
+  reaching `dangerouslySetInnerHTML`), except this one reached the JS interpreter
+  directly.
+
+  `<AnalyticsScripts gaId clarityId />` applies two independent layers:
+  1. **Validation** — each id must match its vendor-documented shape
+     (`GA_MEASUREMENT_ID_PATTERN` = `/^G-[A-Z0-9]{1,32}$/`, per Google Analytics Help
+     12270356; `CLARITY_PROJECT_ID_PATTERN` = `/^[a-z0-9]{1,32}$/`, per Microsoft
+     Learn's published demo project `3t0wlogvdz`). A non-matching id renders NO
+     script at all — analytics silently does not load and the site keeps serving.
+     No minimum length is invented: Google's own docs print the short `G-12345`.
+  2. **Escaping** — the id is emitted as a JSON string literal through the existing
+     `jsonLdScriptContent` escaper, so even a value that skipped layer 1 (a future
+     field with a looser shape, a caller reaching for `gaInitScript` directly) is
+     inert data rather than code.
+
+  Both layers are proven load-bearing by mutation: removing the escaper makes the
+  built body actually call `alert` under test; removing the validation makes the
+  hostile id reach the `googletagmanager` loader URL.
+
+  Also exported for consumers that render their own tags: `isValidGaMeasurementId`,
+  `isValidClarityProjectId`, `gaInitScript`, `clarityInitScript`,
+  `analyticsScriptLiteral`.
+
+  Ships as its own tsup entry (`./analytics`), isolated from the root `index` barrel
+  the same way `./json-ld`, `./cache` and `./route-handlers` are — its only runtime
+  dependencies are `next/script` and the local escaper, so importing it must never
+  drag in `CtaButtons`/`EditableCta`'s `@reblu/site-ui` + `next/link` client graph.
+
+  **Action required for SITE repos:** replace hand-rolled GA/Clarity `<Script>`
+  blocks with `<AnalyticsScripts gaId={analytics?.gaId} clarityId={analytics?.clarityId} />`.
+  `apps/demo-site` migrates onto it in this same change. base-api additionally now
+  refuses to store a malformed id (nexus form) and coerces one to `null` on the way
+  out of `/api/site/analytics`, so a row written before this fix cannot reach a SITE.
+
+## 1.4.0
+
+### Minor Changes
+
+- fe8b8d9: Add `jsonLdScriptContent(value)` and `<JsonLd>` (`@reblu/site-next/json-ld`) — a
+  safe `application/ld+json` `<script>` serialiser/renderer for the App Router.
+
+  A `<script>` element is HTML's "raw text" context: the parser ends it on the
+  first case-insensitive `</script` byte sequence it sees, no matter whether that
+  sequence sits inside a JSON string. `JSON.stringify` escapes for JSON syntax
+  only, so serialising tenant-authored data (page title, description, …) straight
+  into a JSON-LD `<script>` with plain `JSON.stringify` is a stored-XSS sink: a
+  value containing `</script><img src=x onerror=alert(1)>` breaks out of the
+  element and runs. `apps/demo-site` already carried a local fix for exactly this
+  (`generateStructuredData`, escaping `<` only); it has now been extracted here so
+  every SITE gets it instead of reinventing it — `demo-site` migrates onto the
+  shared helper in this same change.
+
+  `jsonLdScriptContent` escapes `<`, `>`, `&`, U+2028 and U+2029 to their
+  `\uXXXX` form. Every one of those is a standard JSON character escape, so
+  `JSON.parse(jsonLdScriptContent(value))` always recovers `value` unchanged —
+  this is an escaper, not a strip/allowlist sanitiser. `<` alone closes the
+  attack; `>`/`&`/U+2028/U+2029 are defence in depth appropriate for published
+  SDK surface (U+2028/U+2029 are valid JSON but invalid raw JS line terminators,
+  which has tripped up naive `<script>` consumers before).
+
+  ## Why `@reblu/site-next`, not `@reblu/site-blocks`
+
+  `@reblu/site-blocks` already ships `sanitizeHtml` for the **HTML** boundary
+  (`dangerouslySetInnerHTML`), which looks like the obvious home. It isn't: that
+  package's main entry bundles `parse5` + the `hast-util-*` chain + `marked` with
+  `treeshake: false` — `dist/index.js` is ~463 KB unminified, and PR #848 spent a
+  full round removing exactly that weight (89 KB gzipped) from a client bundle
+  that only needed one HTML-escaping helper. A 40-line, dependency-free escaper
+  must not drag an HTML parser behind it.
+
+  `<JsonLd>` is also Next-specific (the official App Router
+  `suppressHydrationWarning` pattern), which `@reblu/site-next` already is.
+  It ships as its own tsup entry (`./json-ld`), isolated from the root `index`
+  barrel the same way `./cache` and `./route-handlers` already are — importing
+  it must never drag in `CtaButtons`/`EditableCta`'s `next/link` +
+  `@reblu/site-ui` graph.
+
+  **Measured**: `dist/json-ld.js` is 701 B (451 B gzipped); its only runtime
+  import is `react/jsx-runtime`.
+
+  ## Usage
+
+  ```tsx
+  import { JsonLd } from '@reblu/site-next/json-ld'
+  ;<JsonLd id='page' data={page.jsonLd} />
+  ```
+
+  Or serialise directly:
+
+  ```ts
+  import { jsonLdScriptContent } from '@reblu/site-next/json-ld'
+
+  const html = jsonLdScriptContent(structuredData)
+  ```
+
+  See `@reblu/site-blocks`' README ("Security boundaries") and
+  `@reblu/site-next`'s README ("Structured data (JSON-LD)") for the full
+  HTML-boundary vs. script-boundary pairing.
+
+### Patch Changes
+
+- Updated dependencies [eef13bf]
+  - @reblu/site-contracts@0.4.0
+  - @reblu/site-client@3.0.0
+
+## 1.3.2
+
+### Patch Changes
+
+- Updated dependencies [495d32d]
+  - @reblu/site-contracts@0.3.0
+  - @reblu/site-client@2.0.0
+
+## 1.3.1
+
+### Patch Changes
+
+- Updated dependencies [d081f12]
+- Updated dependencies [06de596]
+  - @reblu/site-contracts@0.2.0
+  - @reblu/site-client@1.0.0
+
+## 1.3.0
+
+### Minor Changes
+
+- 33da822: `AuthLogo` is now "logo XOR name" and owns the auth page's heading. When a logo
+  resolves for the active theme it renders that image wrapped in a heading whose
+  accessible name is `siteName` (via the img `alt`) — so the page always has a
+  heading, but the name is never shown as duplicated visible text next to the
+  logo. When no logo resolves it renders `siteName` (or the fallback label) as the
+  heading text instead of a plain `<span>`. Auth pages should therefore drop their
+  separate `<h1>{siteName}</h1>` — keeping it double-rendered the name whenever no
+  logo was configured (or only the other theme's logo was).
+
+  Adds an optional `headingLevel` prop (default `1`) to control that heading
+  level. The decorative escape hatch is unchanged: `hideTextFallback` or
+  `copy={{ altText: '' }}` still render a bare, unwrapped image for consumers that
+  own the heading themselves.
+
+### Patch Changes
+
+- Updated dependencies [33da822]
+  - @reblu/site-ui@0.3.1
+
+## 1.2.1
+
+### Patch Changes
+
+- b0cbc4c: Reclassify `@reblu/site-ui` from a `peerDependency` to a regular `dependency` (`workspace:^`), matching its siblings `@reblu/site-client` and `@reblu/site-contracts`.
+
+  `@reblu/site-ui` is an internal presentational primitive that `@reblu/site-next` bundles usage of, not a host-provided singleton — unlike `react`/`next`/`next-themes`, which remain peers. Declaring it a peer pinned it to an exact version (`workspace:*` → `0.2.0`), so shipping `@reblu/site-ui@0.3.0` (with the `./tabs`/`./label` subpaths the `./auth` bundle imports) fell out of range and forced a spurious major bump. As a regular dependency (`^0.3.0`) consuming SITEs no longer install `@reblu/site-ui` themselves, resolution to the version carrying `./tabs`/`./label` is automatic, and `@reblu/site-next` stays on 1.x (REB-510).
+
+- Updated dependencies [b0cbc4c]
+  - @reblu/site-ui@0.3.0
+
+## 1.2.0
+
+### Minor Changes
+
+- 14dd092: Add `AuthLogo` + 4 net-new auth components + `createProxyRoute` factory to `@reblu/site-next/auth` and `@reblu/site-next/route-handlers` (REB-510 slice 2b).
+
+  `./auth` now also exports:
+  - `AuthLogo` — dynamic tenant logo (light/dark × expanded/compact), driven by
+    `next-themes` and the 4 `/api/site/config` logo URLs, falling back to
+    `siteName` then a generic label when no logo is configured.
+  - `ResetPasswordRequest` / `ResetPasswordConfirm` (incl. the REB-378 MFA
+    step-up branch) / `SetPassword` / `AuthConfirm` (dual-mode
+    `success=true` vs `token_hash`+`type`) — copy-injectable with Spanish
+    defaults, extracted from demo-site's hand-rolled auth pages.
+
+  A new `./route-handlers` subpath (server-only, dependency-free, no
+  `'use client'`) exports `createProxyRoute(targetPath, opts?)`, a factory that
+  wires a SITE's `app/api/*` Route Handler to base-api's `/api/site/auth/*` in
+  one line — forwarding User-Agent/X-Forwarded-For/X-Real-IP, optionally
+  `Set-Cookie`, with a `requireJson` guard and a lazy per-request
+  `REBLU_API_BASE_URL`/`REBLU_API_KEY` env read (opts still take priority).
+
+  `next-themes` is now a peer dependency (only required by `AuthLogo`).
+
+- ebe163e: Add a UI-free `./cache` subpath for `NextCacheAdapter` and float the SDK deps.
+
+  `@reblu/site-next@1.0.0` only exposed `.` and `./cta-buttons`. The barrel `.`
+  re-exports `NextCacheAdapter` alongside the CTA client components
+  (`CtaButtons`/`StickyMobileCta`/`EditableCta` → `@reblu/site-ui` + `next/link`),
+  so importing the server-only, dependency-free adapter from a server module still
+  dragged in the client boundary — Next 16 + Turbopack RSC then blew up with
+  `createContext is not a function` (same class as the Radix-Slot bug, REB-469).
+  - Add a dedicated `./cache` subpath export mapping only to
+    `next-cache-adapter.ts` (its own `tsup` entry). `NextCacheAdapter` is now
+    importable as `@reblu/site-next/cache` without pulling any UI. The barrel `.`
+    keeps exporting it for backward compatibility.
+  - Float `@reblu/site-client` and `@reblu/site-contracts` from `workspace:*` to
+    `workspace:^`, so a published `@reblu/site-next` resolves `^0.1.1` (the
+    republished packages that ship `dist/`, REB-487) instead of the exact,
+    broken `0.1.0` that `workspace:*` had frozen at publish time.
+
+### Patch Changes
+
+- Updated dependencies [356e04d]
+  - @reblu/site-contracts@0.1.2
+  - @reblu/site-client@0.1.2
+
+## 1.0.0
+
+### Patch Changes
+
+- Updated dependencies [873cad4]
+  - @reblu/site-ui@0.2.0

package/README.md

@@ -18,6 +18,9 @@ intentionally Next-coupled so the lower SDK layers —
 5. **reCAPTCHA v3** (`./recaptcha`) — the SITE's half of the contact-form
    captcha contract: the canonical action, the render gate, and the
    interaction-mount key. See "reCAPTCHA v3" below.
+6. **Academy** (`./academy`) — `AcademyEnrollmentForm`, the anonymous
+   enrollment-request form, plus `deriveValidationFields` to build its
+   per-tenant validation fields from course/config data. See "Academy" below.
 
 ## Install
 
@@ -149,6 +152,71 @@ export const POST = createProxyRoute('/api/site/auth/login')
 `REBLU_API_BASE_URL`/`REBLU_API_KEY` env vars — read lazily per request, not at
 module load.
 
+## Academy
+
+`@reblu/site-next/academy` exports the anonymous academy enrollment-request
+form and the pure helper that derives its validation fields from tenant data.
+
+```tsx
+import { AcademyEnrollmentForm, deriveValidationFields } from '@reblu/site-next/academy'
+
+// `course` is whatever `GET /api/site/academy/courses/[slug]` (via
+// `@reblu/site-client`'s `academy.bySlug`) already returned — this form never
+// re-derives `salesEnabled` or requests anything extra.
+const validationFields = deriveValidationFields(course)
+
+{course.salesEnabled && (
+  <AcademyEnrollmentForm
+    enrollmentRequestUrl="/api/academy/enrollment-requests"
+    courseSlug={course.slug}
+    validationFields={validationFields}
+  />
+)}
+```
+
+`enrollmentRequestUrl` is a SITE-owned Route Handler — the browser can never
+call base-api directly (`X-Reblu-Api-Key` is a server secret). Wire one with
+`createProxyRoute` from `./route-handlers`:
+
+```ts
+// app/api/academy/enrollment-requests/route.ts
+import { createProxyRoute } from '@reblu/site-next/route-handlers'
+
+export const POST = createProxyRoute('/api/site/academy/enrollment-requests')
+```
+
+**PER-TENANT, DATA-DRIVEN — not code-driven.** Whether a course asks for extra
+verification, and which fields it asks for, is entirely tenant configuration:
+
+- Today, `AcademyCourseDetail` exposes only `requiresValidation` +
+  `validationFieldLabel` (a single generic field). `deriveValidationFields`
+  falls back to that one field when no richer list is present.
+- A future tenant-configurable list (e.g. `AcademyConfig.validationFields: [{
+  key, label, required, maxLength? }]`) is accepted by the SAME helper —
+  `AcademyValidationSource` is defined structurally, so a wider real contract
+  type is already assignable without an SDK release. Arbitrary keys (a
+  colegiado number, a professional college, anything a tenant configures) work
+  the moment the data carries them; `AcademyEnrollmentForm` never hardcodes a
+  field name — it only ever iterates the `validationFields` array it was given.
+- A tenant with no validation requirement passes `validationFields={[]}` (or
+  omits the prop, `[]` is the default) — the form renders only the email
+  field.
+
+**Never a purchase confirmation.** The upstream route
+(`POST /api/site/academy/enrollment-requests`) replies UNIFORMLY whether the
+email was brand-new (a request row was created) or already known (a sign-in
+link was sent, nothing created) — anti-enumeration by design. The form's
+always-visible copy says the request goes to human review and that no
+automatic charge happens; `onSubmitted` fires on any 2xx and must never be
+read as "a request was recorded".
+
+**Field-level errors.** A non-2xx JSON body shaped like `{ error, details:
+{ fieldErrors } }` (`ApiErrorBody`/`ApiErrorDetails` from `@reblu/site-client`)
+maps each `fieldErrors` key onto the matching input (`email`, or a
+`validationFields[].key`) and focuses the first one; anything else — no
+`details`, or a `429` — renders as a single form-level error instead. No
+reCAPTCHA: the route is IP rate-limited server-side.
+
 ## Structured data (JSON-LD)
 
 `@reblu/site-next/json-ld` (REB-622, server-only, dependency-free) renders one