@reblu/site-client 5.18.0 → 5.20.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @reblu/site-client
 
+## 5.20.0
+
+### Minor Changes
+
+- 93143eb: Reviews (REB-1272). `@reblu/site-contracts` exports the `Review` and `ReviewSource` types of `GET /api/site/reviews`. `@reblu/site-client` adds `client.reviews.list({ pageId?, limit? }, cache?)`: the tenant's published reviews in the order set in nexus, optionally only one page's (404 without the tenant's `reviews` module). `@reblu/site-blocks` adds `Reviews`, a Server Component drop-in: a responsive grid with an accessible star rating, the author, the date, the text and a «Ver en <fuente>» link to the original (new tab, `rel="noopener nofollow"`), plus an optional tenant `notice` above or below the grid. Every existing export and namespace is unchanged.
+
+## 5.19.0
+
+### Minor Changes
+
+- 9a83295: Guest course checkout (REB-1264). Additive only: every existing export behaves as before.
+  - `@reblu/site-contracts` exports `AcademyCheckoutRequest`, `AcademyCheckoutBilling`, `AcademyCheckoutSession` and `AcademyCheckoutErrorCode` (`POST /api/site/academy/checkout`).
+  - `@reblu/site-client` adds `client.academy.checkout(body, options?)` → `{ url, sessionId }` (Stripe URL re-checked like `shop.checkout()`); a refusal throws `AcademyCheckoutError` (an `ApiError`) with the stable `code` and `details`.
+  - `@reblu/site-next` adds `createAcademyCheckoutRoute()` in `./route-handlers`: forwards `x-reblu-visitor-ip`, fills `successUrl`/`cancelUrl` on `coursePath` and re-checks the Stripe URL. `createShopCheckoutRoute` now shares that code, unchanged in behaviour.
+  - `@reblu/site-blocks` adds the drop-in `CourseGuestCheckoutForm` (`./client`): name, surname, email, terms box, the course's consent box, optional full invoice, total and pay notice; it gives way to the request form on `ENROLLMENT_REQUEST_REQUIRED`. The root entry adds `courseSellsAsGuest` and `toAcademyCheckoutInvoiceFields`.
+
 ## 5.18.0
 
 ### Minor Changes

package/README.md

@@ -199,13 +199,14 @@ resource; list methods return `{ data, meta? }` (pagination metadata preserved).
 | `analytics`   | `get()`                                                                                                                                                                                   |
 | `legal`       | `get()` — privacy, terms, cookies, `legalNotice`, `withdrawalPolicy`                                                                                                                       |
 | `trustBadges` | `list(params?)` — `{ type? }`; only active badges inside their validity window                                                                                                            |
+| `reviews`     | `list(params?)` — `{ pageId?, limit? }`; published reviews only (REB-1272). 404 without the tenant's `reviews` module |
 | `ctas`        | `list(slot)`                                                                                                                                                                              |
 | `blog`        | `list(params?)`, `bySlug(slug)`, `related(slug)`, `categories()`, `slugs()`, `preview(id)`                                                                                                |
 | `pages`       | `list(params?)`, `bySlug(slug)`, `featured(category, opts?)`, `slugs()`                                                                                                                   |
 | `dataRequests` | `submit(body, options?)` (write)                                                                                                                                                         |
 | `withdrawalRequests` | `submit(body, options?)` (write) — REB-1201 withdrawal form                                                                                                                       |
 | `shop`        | `products(params?)`, `facets(params?)`, `bySlug(slug)`, `categories()`, `config()`, `checkout(body)`, `quote(body, opts?)`, `validateCart(body)`, `applyDiscount(body)`, `checkEmail(body)`, `order(sessionId)` |
-| `academy`     | `courses(params?)`, `bySlug(slug)`, `categories()`, `lessonPreview(courseSlug, lessonSlug)`, `enrollmentRequest(body, options?)` (write) |
+| `academy`     | `courses(params?)`, `bySlug(slug)`, `categories()`, `lessonPreview(courseSlug, lessonSlug)`, `checkout(body, options?)` (write, REB-1264), `enrollmentRequest(body, options?)` (write) |
 
 Every method accepts an optional trailing `RebluCachePolicy` (`{ revalidate }`) to
 override caching per call. `blog.preview` is always uncached (draft content), and so is
@@ -229,6 +230,23 @@ const { data: badges } = await client.trustBadges.list({}, { revalidate: 3600 })
 `{ revalidate: false }` (or `0`) fetches on every request when a badge must
 disappear the moment its window closes.
 
+#### Reviews (REB-1272)
+
+`reviews.list()` returns the tenant's **published** reviews in the order set in
+nexus («Reseñas»). Each one carries its source and an `https://` link to the
+original, so a visitor can check it. Pass a page's `id` for only the reviews
+linked to that page (a treatment, a specialty, a professional's profile), and
+`limit` for at most that many:
+
+```ts
+const { data: home } = await client.reviews.list({ limit: 6 }, { revalidate: 3600 })
+const { data: forPage } = await client.reviews.list({ pageId: page.id })
+```
+
+The endpoint answers 404 when the tenant does not have the `reviews` module, so
+catch it and render nothing: `.catch(() => ({ data: [] }))`. Render the list
+with `Reviews` from `@reblu/site-blocks`.
+
 `pages.bySlug(slug)` returns a `PageDetail` whose `blocks[]` mirror their
 parent section's `heading`/`backgroundColor`/`cta`, with embed blocks
 (`doctor_embed`/`specialty_embed`) additionally carrying a server-resolved
@@ -357,6 +375,47 @@ const ack = await client.withdrawalRequests.submit({
 Same rejections as `dataRequests.submit` (`400`, `422`, `429`). For the drop-in
 form see `WithdrawalRequestForm` in `@reblu/site-blocks/client`.
 
+#### Guest course checkout (REB-1264)
+
+`academy.checkout(body, options?)` buys a course that needs no validation in
+one step (`POST /api/site/academy/checkout`) and returns the Stripe Checkout
+`{ url, sessionId }`; the account is created after payment. The answer never
+depends on whether the email has an account. The `url` is re-checked like
+`shop.checkout()`'s (`UnsafeCheckoutRedirectError`).
+
+```ts
+import { AcademyCheckoutError, visitorIpFromHeaders } from '@reblu/site-client'
+
+try {
+  const { url } = await client.academy.checkout(
+    {
+      courseSlug: 'intro',
+      firstName: 'Ada',
+      lastName: 'Lovelace',
+      email: 'ada@example.com',
+      acceptsTerms: true,
+      termsVersionId: shopConfig.checkout.termsVersion?.id, // when the tenant published terms
+      acceptsWithdrawalWaiver: true, // when course.withdrawalConsent is not null…
+      withdrawalWaiverVersion: course.withdrawalConsent?.version, // …and its version
+      successUrl: 'https://site.example/academy/intro?pago=ok&session_id={CHECKOUT_SESSION_ID}',
+      cancelUrl: 'https://site.example/academy/intro?pago=cancelado',
+    },
+    { visitorIp: visitorIpFromHeaders(request.headers) },
+  )
+  // redirect the buyer to `url`
+} catch (e) {
+  if (e instanceof AcademyCheckoutError && e.code === 'ENROLLMENT_REQUEST_REQUIRED') {
+    // validation required or free course: use academy.enrollmentRequest instead
+  }
+}
+```
+
+A refusal throws `AcademyCheckoutError` (an `ApiError`) with the stable `code`
+(`AcademyCheckoutErrorCode`), `details` (`field`, `reason`, `fieldErrors`
+with one message per field, or `missing` on `INVOICING_NOT_READY`) and the server's `errorMessage`. For the drop-in
+form see `CourseGuestCheckoutForm` in `@reblu/site-blocks/client`, with
+`createAcademyCheckoutRoute` from `@reblu/site-next/route-handlers`.
+
 #### Contact form metadata — the page the lead came from (REB-1077)
 
 Build the contact form's `metadata` with `buildContactFormMetadata()` in the
@@ -406,7 +465,7 @@ await client.contactForm.submit(payload, {
 })
 ```
 
-`shop.checkEmail` and `academy.enrollmentRequest` take the same `options`
+`shop.checkEmail`, `academy.checkout` and `academy.enrollmentRequest` take the same `options`
 (REB-1006): base-api keys their per-IP limits on `x-reblu-visitor-ip` too.
 
 Without `visitorIp` base-api applies only the per-tenant limit to the public

package/dist/index.cjs

@@ -131,6 +131,69 @@ function apiErrorRawBody(error) {
   const prefix = `API ${error.status} @ ${error.path}: `;
   return error.message.startsWith(prefix) ? error.message.slice(prefix.length) : error.message;
 }
+function toAcademyCheckoutDetails(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const raw = value;
+  const details = {};
+  if (typeof raw.field === "string") details.field = raw.field;
+  if (typeof raw.reason === "string") details.reason = raw.reason;
+  if (Array.isArray(raw.missing) && raw.missing.every((item) => typeof item === "string")) {
+    details.missing = raw.missing;
+  }
+  if (typeof raw.fieldErrors === "object" && raw.fieldErrors !== null && !Array.isArray(raw.fieldErrors)) {
+    const fieldErrors = Object.fromEntries(
+      Object.entries(raw.fieldErrors).filter(
+        (entry) => typeof entry[1] === "string"
+      )
+    );
+    if (Object.keys(fieldErrors).length > 0) details.fieldErrors = fieldErrors;
+  }
+  return Object.keys(details).length > 0 ? details : void 0;
+}
+function parseAcademyCheckoutBody(rawBody) {
+  try {
+    const parsed = JSON.parse(rawBody);
+    if (typeof parsed !== "object" || parsed === null) return {};
+    const details = toAcademyCheckoutDetails(parsed.details);
+    return {
+      ...typeof parsed.error === "string" ? { error: parsed.error } : {},
+      ...isAcademyCheckoutErrorCode(parsed.code) ? { code: parsed.code } : {},
+      ...details ? { details } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+var ACADEMY_CHECKOUT_CODE_SET = {
+  INVALID_INPUT: true,
+  RATE_LIMITED: true,
+  COURSE_NOT_FOUND: true,
+  SALES_CLOSED: true,
+  ENROLLMENT_REQUEST_REQUIRED: true,
+  INVOICING_NOT_READY: true,
+  TERMS_NOT_ACCEPTED: true,
+  TERMS_VERSION_CHANGED: true,
+  CONSENT_REQUIRED: true,
+  CONSENT_VERSION_CHANGED: true,
+  INVALID_BILLING: true
+};
+function isAcademyCheckoutErrorCode(value) {
+  return typeof value === "string" && Object.hasOwn(ACADEMY_CHECKOUT_CODE_SET, value);
+}
+var AcademyCheckoutError = class extends ApiError {
+  code;
+  details;
+  errorMessage;
+  constructor(source) {
+    const rawBody = apiErrorRawBody(source);
+    super(source.status, source.path, rawBody);
+    this.name = "AcademyCheckoutError";
+    const parsed = parseAcademyCheckoutBody(rawBody);
+    this.code = parsed.code;
+    this.details = parsed.details;
+    this.errorMessage = parsed.error;
+  }
+};
 
 // src/client.ts
 var RETRY_AFTER_CAP_MS = 2e3;
@@ -305,6 +368,38 @@ function makeAcademyNamespace(ctx) {
     categories: (cache) => requestList(ctx, "/api/site/academy/categories", {
       cachePolicy: cache
     }),
+    /**
+     * REB-1264 — guest checkout of a course that needs no validation: name,
+     * email, the accepted terms version, the course's consent box version
+     * and, optionally, full-invoice data. Returns the Stripe Checkout `url`
+     * to send the buyer to; the account is created after payment. The
+     * answer never depends on whether the email has an account.
+     *
+     * The `url` is re-checked like `shop.checkout()` (`https:` on
+     * `ctx.checkoutRedirectHosts`, else {@link UnsafeCheckoutRedirectError}).
+     * A refusal throws {@link AcademyCheckoutError} with its stable `code`;
+     * on `ENROLLMENT_REQUEST_REQUIRED` use `enrollmentRequest` instead.
+     *
+     * Server-side, pass `options.visitorIp` (see `visitorIpFromHeaders`):
+     * base-api keys this route's per-visitor limit on it.
+     */
+    checkout: async (body, options) => {
+      let session;
+      try {
+        session = await requestMutation(
+          ctx,
+          "/api/site/academy/checkout",
+          body,
+          options
+        );
+      } catch (error) {
+        throw error instanceof ApiError ? new AcademyCheckoutError(error) : error;
+      }
+      if (!isSafeCheckoutRedirectUrl(session.url, ctx.checkoutRedirectHosts)) {
+        throw new UnsafeCheckoutRedirectError(session.url, ctx.checkoutRedirectHosts);
+      }
+      return session;
+    },
     /**
      * Submit an anonymous enrollment request for a course.
      *
@@ -577,6 +672,18 @@ function makeShopNamespace(ctx) {
   };
 }
 
+// src/domains/reviews.ts
+function makeReviewsNamespace(ctx) {
+  function list(params = {}, cache) {
+    return requestList(
+      ctx,
+      buildUrl("/api/site/reviews", { pageId: params.pageId, limit: params.limit }),
+      { cachePolicy: cache }
+    );
+  }
+  return { list };
+}
+
 // src/domains/trust-badges.ts
 function isCachePolicy(value) {
   return Object.prototype.hasOwnProperty.call(value, "revalidate");
@@ -658,10 +765,12 @@ function createRebluClient(config) {
     contactForm: makeContactFormNamespace(ctx),
     leads: makeLeadsNamespace(ctx),
     dataRequests: makeDataRequestsNamespace(ctx),
-    withdrawalRequests: makeWithdrawalRequestsNamespace(ctx)
+    withdrawalRequests: makeWithdrawalRequestsNamespace(ctx),
+    reviews: makeReviewsNamespace(ctx)
   };
 }
 
+exports.AcademyCheckoutError = AcademyCheckoutError;
 exports.AmbiguousPageSlugError = AmbiguousPageSlugError;
 exports.ApiError = ApiError;
 exports.DEFAULT_CHECKOUT_REDIRECT_HOSTS = DEFAULT_CHECKOUT_REDIRECT_HOSTS;