@reblu/site-contracts 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,304 @@
+# @reblu/site-contracts
+
+## 1.0.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`.
+
+## 1.0.0
+
+### Major Changes
+
+- 340db30: REB-659 — phone fields on the SITE API are now E.164, and two public boundaries
+  changed behaviour. A consuming SITE should read this before upgrading.
+
+  **Type change.** `ShopAddressInput.phone` and `ShopCheckoutInput.customerPhone`
+  widen from `string | undefined` to `string | null | undefined`. `null` is now a
+  real state meaning "clear this phone", which the server accepts and the previous
+  type could not express. Existing code that only ever assigns a string keeps
+  compiling.
+
+  **Behaviour change — `POST /api/site/contact-form` and `POST /api/site/leads`
+  (more permissive).** These used to store whatever string arrived. They now
+  resolve it to E.164 against the tenant's configured country
+  (`SiteSettings.addressCountry` in nexus). A form that posts what a person typed
+  — `922 123 456`, `(922) 123-456`, `0034 922 123 456` — keeps working and the
+  value is stored as `+34922123456`.
+
+  On `/api/site/leads` the phone stays optional: an absent key, `''` and
+  whitespace all store no phone, exactly as before.
+
+  A **non-blank** value that cannot be stored now returns an error instead of an
+  undialable string. There are two branches, and they answer differently:
+  - **shape** — shorter than 6 or longer than 32 characters, or containing
+    anything outside digits, spaces, `+`, dashes, parentheses and dots. An
+    extension always lands here, whichever way it is written (`x22`, `ext. 22`,
+    `;ext=22`, `#22`, `,22`), because every marker for one is outside that
+    allowlist — E.164 cannot represent an extension, so it is refused rather than
+    silently truncated to the switchboard. `/api/site/contact-form` answers 400;
+    `/api/site/leads` answers **422**, its long-standing status for a malformed
+    payload on any field. On that 422 the actionable message is in
+    `details.fieldErrors.phone` — the top-level `error` is the generic
+    `Validation error`.
+  - **resolution** — looks like a phone but cannot be resolved: the library does
+    not recognise it, or it lacks an international prefix while the tenant has no
+    country configured. **400** on both endpoints, with the message in `error` and
+    in `details.fieldErrors.phone`.
+
+  So: read `details.fieldErrors.phone` rather than branching on the status, and
+  do not assume the two endpoints answer with the same code for a bad shape.
+
+  On both endpoints the resolution prefers the LOCAL reading for a prefix-less
+  number over the international one, because the caller is typing (or posting)
+  into one specific tenant's form. The residual: a prefix-less number that is
+  also a valid national number of the tenant's own country is normalised into
+  that country rather than refused — for a Spanish tenant, Myanmar digits
+  `951234567` become `+34951234567`. The alternative — preferring the
+  international reading — reopens a different and worse class this file's own
+  header documents (a US number silently reading as Egyptian), so this is a
+  chosen trade, not an oversight. Quantifying how often the residual is actually
+  hit is a follow-up issue.
+
+  **Read-path change — `GET /api/site/config` (same shape, different VALUE).**
+  No field was added or removed here, but the VALUE of `address.telephone`
+  changes once the phone backfill runs against a tenant: today it can read
+  `34922123456` (the legacy shape stored before this issue); after the backfill
+  it reads `+34922123456`. Any SITE that pattern-matches or otherwise assumes the
+  prefix-less shape when rendering this field (a `tel:`/`wa.me` link builder,
+  for instance) should read this before the backfill runs against its tenant.
+
+  **Behaviour change — `POST /api/site/shop/checkout` (stricter).**
+  `customerPhone` and `shippingAddress.phone` must now be E.164 (`+34…`) or
+  absent; a bare local number is rejected. Unlike the contact form this payload is
+  assembled by the SITE from a cart rather than typed by a person at that moment,
+  so there is no "typed locally for this tenant" provenance to resolve against.
+
+  **Why the SDK does not build E.164 for you.** Every SITE would construct it
+  differently and each would be wrong in its own way — which is the defect this
+  issue fixes one layer down. The platform owns the rule because the platform is
+  the layer that knows the tenant's country. A shared formatter helper for SITEs
+  is REB-703, and it comes after this.
+
+  ***
+
+  **This release is `1.0.0`, and that is deliberate — see REB-755.**
+
+  `@reblu/site-contracts` has been at `0.x` while `@reblu/site-client` reached
+  4.0.1. That ordering is hard to defend, and it had a concrete cost: consumers
+  pin `^0.5.0`, and **a caret on `0.x` does not cross the minor** (verified with
+  `semver@7`: `^0.5.0` admits `0.5.3`, not `0.6.0`). So every change — additive or
+  breaking — cost every consuming SITE repo a hand edit. The careful work of
+  deciding whether a change breaks anything bought nobody anything.
+
+  This release is breaking regardless, so the adoption is already owed. Shipping
+  `1.0.0` here means the toll and the breaking change are **one edit rather than
+  two** — a bare `1.0.0` later would make this a `2.0.0` and cost an extra
+  adoption for nothing.
+
+  From here, `^1.0.0` carries every additive change automatically. REB-651
+  (SEO fields, additive by design) lands as `1.1.0` and reaches consumers with no
+  edit. REB-665 reshapes `Config` and will be `2.0.0`.
+
+  `1.0.0` is not a claim that the contract is finished. It is a claim that
+  breakage will be signalled through the major — which we were doing anyway, into
+  a version range where it had no effect.
+
+## 0.5.0
+
+### Minor Changes
+
+- 7dcfb4f: `Config` gains a `fiscal` block — the tenant's tax identifier, registered name
+  and official registry entry — plus the types `ConfigFiscal`,
+  `ConfigFiscalRegistry` and `ConfigTaxIdKind`.
+
+  A Spanish commercial site is legally required to publish its tax identifier, and
+  until now no tenant could enter one: `SiteSettings` had no `cif`, no `nif`, no
+  `taxId` and no registered name distinct from the trading name. Every SITE that
+  needed one therefore hardcoded it — the Dermamedicin footer carries
+  `B-XXXXXXXX` as a literal in its own repo, which is wrong for every other tenant
+  by construction. REB-73 (downloadable PDF invoice) was silently blocked on the
+  same gap: an invoice without the issuer's CIF is not a valid invoice.
+
+  ## Shape
+
+  ```ts
+  type ConfigFiscal = {
+    taxId: string | null
+    taxIdKind: 'NIF' | 'CIF' | null
+    legalName: string | null
+    registry: { name: string; number: string } | null
+  }
+
+  // on Config:
+  fiscal: ConfigFiscal | null
+  ```
+
+  ## `taxIdKind` — why the SITE is told which document it is holding
+
+  A tenant holds exactly one tax identifier, but it is not one document. In Spain
+  an autónomo files a **NIF** (8 digits + a mod-23 control letter, or a NIE for a
+  foreign resident) and every other legal form files a **CIF** (organisation
+  letter + 7 digits + a control character that is a digit for some organisation
+  letters and a letter for others). Which applies is derivable only from
+  `businessType`.
+
+  So `taxId` alone would force every SITE to re-implement that derivation, and a
+  SITE that hardcoded `CIF:` would print the wrong word next to an autónomo's
+  number. `taxIdKind` carries the platform's single derivation, and a SITE renders
+  the label verbatim:
+
+  ```tsx
+  {
+    config.fiscal?.taxId && (
+      <span>
+        {config.fiscal.taxIdKind}: {config.fiscal.taxId}
+      </span>
+    )
+  }
+  ```
+
+  `taxId` is stored normalised (uppercase, separators stripped), so it is safe to
+  render as-is.
+
+  ## `legalName` carries no fallback, on purpose
+
+  `legalName` is the registered name / razón social, which routinely differs from
+  the trading name in `business.name` ("Dermamedicin" vs "Dermamedicin Canarias,
+  S.L."). It is `null` when unset and does **not** silently fall back to the
+  trading name: a legal footer and an invoice need the registered one, and quietly
+  substituting the other would publish the wrong name on a document with legal
+  weight. A SITE that wants a fallback writes it itself, seeing that it is doing
+  so.
+
+  ## `registry` is sector-agnostic, and both-or-nothing
+
+  `registry` is a free-text `name` plus a `number`, not a `healthRegistryNumber`.
+  Every regulated sector is entered in one of these and only the registry's name
+  differs: Registro Sanitario for a clinic, RGSEAA for a restaurant, Registro de
+  Turismo for a hotel, a colegiado number for a self-employed professional, a
+  Registro Mercantil entry for a company. Naming the field after the first
+  tenant's sector would put medical vocabulary into a niche-agnostic contract,
+  which is the defect REB-628 exists to undo.
+
+  The object is `null` unless **both** members were filled in. A bare number with
+  no registry named is unreadable in a footer; a registry named with no number is
+  decorative.
+
+  ## Absence
+
+  `fiscal` is `null` when the tenant has entered nothing at all — the same shape
+  `address` and `social` already use. That is the signal to render **no** legal
+  block, rather than a block of empty labels. The underlying columns are nullable
+  with no default and are never backfilled, so "empty" here means "the owner has
+  never filled this in", never "filled in blank".
+
+  Additive: no existing field changed and no existing consumer breaks.
+
+## 0.4.0
+
+### Minor Changes
+
+- eef13bf: Expose typed professional-profile fields on `Page`/`pages.list`, widen the list filter beyond the legacy DB page type, and add the pagination/sort params `pages.list` was missing.
+
+  `pageType='team'` pages carry a structured, sector-agnostic professional
+  profile (role, structured CV, social links) — previously trapped in
+  `Page.metadata`, which never reached the wire. `pageListItemSchema` and
+  `pageDetailSchema` now expose it as a typed `professional` field (`null` for
+  every other pageType).
+  - `@reblu/site-contracts` (minor, additive-only) publishes `ProfessionalSummary`,
+    `ProfessionalProfile`, `ProfessionalCv`, `ProfessionalCvEntry`,
+    `ProfessionalLanguage`, `ProfessionalLanguageLevel`, `ProfessionalSocialLink`,
+    `ProfessionalSocialPlatform`, and `PagesListSort`.
+  - `@reblu/site-client` (major — see below) `pages.list({ type })` is widened
+    from `LegacyPageType` (SERVICE|CUSTOM) to the flexible `PageType`
+    (service|custom|treatments|specialties|team|generic) — the value space the
+    route actually filters on. A typed SITE can now request `type: 'team'`
+    without escaping its own types. `type` also accepts an array for a
+    multi-type filter (repeated `?type=`).
+  - `pages.list` also gains `page`/`pageSize`/`sort` — `pagesListParamsSchema`
+    already accepted them and the route already returns a populated `meta`
+    (total/page/limit/pages), but `PagesListParams` exposed none of it, so a
+    typed caller had no way to request page 2 or change sort. Note the param
+    is `pageSize`, not `limit` — pages and blog genuinely differ (this route
+    reads `pageSize`; blog's reads `limit`), while the response `meta.limit`
+    key is the same word for a different request param on this endpoint.
+
+  **Breaking (major, not minor):** `PagesListParams.type`'s value space changes
+  from `LegacyPageType` to `PageType` — a caller passing `'SERVICE'`/`'CUSTOM'`
+  literally will no longer typecheck. No runtime behavior changes for existing
+  callers: the route was already silently dropping those values, since it only
+  ever validated the lowercase flexible set — but the type change itself is a
+  real breaking change for compilation, so this ships as major rather than
+  minor even though nothing behaves differently at runtime.
+
+## 0.3.0
+
+### Minor Changes
+
+- 495d32d: Relax the contact-form input contract and add a `NOT_CONFIGURED` contact-form mode.
+
+  `ContactFormInput` now marks `surname` and `businessName` OPTIONAL. The contract
+  had required both from every caller, which made it a B2B lead-capture shape: a
+  clinic patient, a diner or a shopper has no company name, and a payload without
+  one died with a 400 before the captcha was ever consulted. Purely a relaxation —
+  a caller that already sends both keeps typechecking unchanged.
+
+  `ContactFormMode` gains a fifth member, `NOT_CONFIGURED`. No tenant was ever
+  provisioned with a `site_integration_config` row, and every read site coalesced
+  the absent row to `DISABLED` — so a brand-new tenant's SITE was told its owner had
+  switched the contact form off, a decision nobody had made. `NOT_CONFIGURED` is
+  that missing state named honestly: nobody has chosen yet. It is never selectable
+  by an owner; only provisioning writes it.
+
+  **Consumers doing an exhaustive `switch` on `ContactFormMode` must handle the new
+  member.** Treat it as non-operational — like `DISABLED`, it accepts no
+  submissions. The two differ only in what they say about _why_, which is the point:
+  a SITE can reasonably prompt the owner to finish setup on `NOT_CONFIGURED` while
+  staying quiet on `DISABLED`.
+
+  Note this is a minor rather than a patch because of that enum widening. The
+  package is pre-1.0, so a `switch` without a default is the realistic break.
+
+## 0.2.0
+
+### Minor Changes
+
+- d081f12: Expose the academy course catalogue through the SDK.
+
+  The headless academy endpoints shipped in REB-528/REB-534, but their contract
+  file was never re-exported from base-api's contracts barrel, so the types could
+  not reach `@reblu/site-contracts` and SITEs had no typed way to call them.
+  - `@reblu/site-contracts` publishes the catalogue DTOs: `AcademyCourseSummary`,
+    `AcademyCourseDetail`, `AcademyCategoryPublic`, `AcademyModulePublic`,
+    `AcademyLessonPublic`, `AcademyInstructorPublic`, and the `AcademyCourseSort`
+    query union.
+  - `@reblu/site-client` adds the `academy` namespace: `academy.courses(params?)`
+    (filtered + paginated), `academy.bySlug(slug)`, and `academy.categories()`.
+    `sort` is typed as a union because the server silently ignores an unknown key,
+    so a typo is now a compile error instead of a no-op falling back to default
+    order.
+
+  Additive only — no existing export changes shape.
+
+## 0.1.2
+
+### Patch Changes
+
+- 356e04d: Republish with `dist/` included and shop surface exposed.
+
+  `0.1.0` was published broken: the bootstrap publish ran without a build, so the
+  tarball shipped only `LICENSE`, `README.md`, and `package.json` — `dist/` was
+  absent and `main`/`module`/`types` pointed at files that did not exist, making
+  both packages unusable when installed.
+  - Add a `prepack` lifecycle script to both packages so `pnpm pack` / `npm pack`
+    / `npm publish` always run the build and emit `dist/` into the tarball. Build
+    before publish is now enforced by the package itself, not only by CI.
+  - `@reblu/site-client` ships the `shop` domain (`domains/shop.ts`) and
+    `@reblu/site-contracts` exports the matching shop types, so the SITE API shop
+    surface is available to external consumers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reblu/site-contracts",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "description": "Public, dependency-free TypeScript types for the Reblu SITE API (types only — no Zod, no Prisma at runtime).",
   "license": "Apache-2.0",
@@ -43,7 +43,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "devDependencies": {
     "@size-limit/preset-small-lib": "^11.1.6",