@reblu/site-client 5.17.0 → 5.19.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @reblu/site-client
 
+## 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
+
+- 07667bc: Single-step checkout, pre-payment summary (REB-1197): `client.shop.quote(body, { visitorIp? })` calls `POST /api/site/shop/quote`; `@reblu/site-next/shop-route-handlers` adds `createShopQuoteRoute()` (forwards the `sb-*` auth cookies, like checkout, so the staff discount is quoted too); `@reblu/site-next/shop` adds `useShopQuote(input, { endpoint?, debounceMs? })`, which re-asks the quote whenever the cart, the code or the delivery choice changes and drops stale answers.
+
 ## 5.17.0
 
 ### Minor Changes

package/README.md

@@ -204,8 +204,8 @@ resource; list methods return `{ data, meta? }` (pagination metadata preserved).
 | `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)`, `validateCart(body)`, `applyDiscount(body)`, `checkEmail(body)`, `order(sessionId)` |
-| `academy`     | `courses(params?)`, `bySlug(slug)`, `categories()`, `lessonPreview(courseSlug, lessonSlug)`, `enrollmentRequest(body, options?)` (write) |
+| `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)`, `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
@@ -298,9 +298,16 @@ failing.
 
 ### Write endpoints
 
-`shop.checkout`, `shop.validateCart` and `shop.applyDiscount` send typed
-`@reblu/site-contracts` request bodies without caching. Checkout error
-handling uses `ApiError.body` as shown above.
+`shop.checkout`, `shop.quote`, `shop.validateCart` and `shop.applyDiscount`
+send typed `@reblu/site-contracts` request bodies without caching. Checkout
+error handling uses `ApiError.body` as shown above.
+
+`shop.quote(body, opts?)` (REB-1197) returns the pre-payment summary of the
+single-step checkout (`ShopQuote`): lines, discount, delivery mode, shipping,
+tax, weight, delivery term, the small print with `{total}` filled, and the
+final total, priced by the same function as `shop.checkout` — the total shown
+is the total Stripe charges. Server-side, pass `{ visitorIp }`: a quote with a
+`discountCode` counts against the per-visitor discount limit.
 
 `shop.checkEmail` is **deprecated** (REB-834) and removed in the next major.
 The endpoint used to say whether an email had an account — an enumeration
@@ -350,6 +357,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
@@ -399,7 +447,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.
      *
@@ -527,6 +622,17 @@ function makeShopNamespace(ctx) {
       "/api/site/shop/validate-cart",
       body
     ),
+    /**
+     * REB-1197 — the pre-payment summary of the single-step checkout: lines,
+     * discount, delivery, shipping, tax, weight, delivery term and the final
+     * total, priced by the same function as `checkout` (the total shown is the
+     * total Stripe charges). Holds nothing: no discount slot, no session.
+     *
+     * Server-side, pass `options.visitorIp` (see `visitorIpFromHeaders`): a
+     * quote with a `discountCode` counts against the same per-visitor limit
+     * as `applyDiscount`.
+     */
+    quote: (body, options) => requestMutation(ctx, "/api/site/shop/quote", body, options),
     /** Validate a discount code against the current cart subtotal. */
     applyDiscount: (body) => requestMutation(
       ctx,
@@ -651,6 +757,7 @@ function createRebluClient(config) {
   };
 }
 
+exports.AcademyCheckoutError = AcademyCheckoutError;
 exports.AmbiguousPageSlugError = AmbiguousPageSlugError;
 exports.ApiError = ApiError;
 exports.DEFAULT_CHECKOUT_REDIRECT_HOSTS = DEFAULT_CHECKOUT_REDIRECT_HOSTS;