@reblu/site-client 5.12.0 → 5.14.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _reblu_site_contracts from '@reblu/site-contracts';
-import { AcademyCourseSort, PaginationMeta, PageType, PagesListSort, ShopSort, TrustBadgeType, ContactFormInput } from '@reblu/site-contracts';
+import { AcademyCourseListQuery, PaginationMeta, PageType, PagesListSort, ShopSort, TrustBadgeType, ContactFormInput } from '@reblu/site-contracts';
 
 /**
  * Cache adapter — the seam that severs the SDK from any framework's caching
@@ -91,28 +91,21 @@ interface ShopProductsParams {
 /**
  * Query params for `academy.courses` (REB-507), grounded on
  * `GET /api/site/academy/courses` — see `parseCourseListParams` in base-api.
+ * Since REB-547 this IS the documented query contract (`AcademyCourseListQuery`,
+ * the same keys the OpenAPI document lists), so the SDK cannot drift from it.
  *
  * Server-side clamping the caller should know about: `limit` is clamped to 1..50
  * and `page` to >= 1, so an out-of-range value is silently corrected rather than
- * rejected. `q`/`instructor`/`category` are truncated (200/64/120 chars).
- * `free: true` means "price is 0" and OVERRIDES any priceMin/priceMax range.
- * `sort` is a union because an unrecognized key is ignored server-side — typing
- * it makes a typo a compile error instead of a silent fall-back to default order.
+ * rejected. `q`/`category` are truncated (200/120 chars).
+ * - `category`: a `CourseCategory` slug. Only ACTIVE categories ever match.
+ * - `instructor`: a user id from `academy.instructors()`. A value that is not a
+ *   uuid matches no course.
+ * - `priceMin`/`priceMax`: inclusive, in integer cents.
+ * - `free: true` means "price is 0" and OVERRIDES any priceMin/priceMax range.
+ * - `sort` is a union because an unrecognized key is ignored server-side — typing
+ *   it makes a typo a compile error instead of a silent fall-back to default order.
  */
-interface AcademyCourseListParams {
-    page?: number;
-    limit?: number;
-    q?: string;
-    sort?: AcademyCourseSort;
-    /** A `CourseCategory` slug. Only ACTIVE categories ever match. */
-    category?: string;
-    /** A user id — `Course.instructorIds` is a denormalized user-uuid array. */
-    instructor?: string;
-    /** Restrict to free courses (priceCents = 0); overrides priceMin/priceMax. */
-    free?: boolean;
-    priceMin?: number;
-    priceMax?: number;
-}
+type AcademyCourseListParams = AcademyCourseListQuery;
 /**
  * Body of `academy.enrollmentRequest`, grounded on
  * `POST /api/site/academy/enrollment-requests`.
@@ -146,6 +139,10 @@ interface AcademyEnrollmentRequestResult {
     message: string;
 }
 
+/** Memo store of one server request, keyed by read identity (REB-1214). */
+type RequestScope = () => Map<string, Promise<unknown>> | undefined;
+/** Upper bound for a `Retry-After` wait before the single retry (REB-1214). */
+declare const RETRY_AFTER_CAP_MS = 2000;
 /**
  * Header carrying the visitor IP from a SITE server to base-api (REB-1005).
  * base-api keys its per-visitor limit on public writes on it, and trusts it
@@ -385,6 +382,13 @@ interface RebluClientConfig {
      * a Stripe CLI mock host) — never to widen production trust.
      */
     checkoutRedirectHosts?: string[];
+    /**
+     * REB-1214 — memo store of the current server request, so identical GET
+     * reads within it are fetched once. In Next.js pass `rebluRequestScope`
+     * from `@reblu/site-next` (React `cache()`); see the README. Without it,
+     * identical GETs share one fetch only while in flight.
+     */
+    requestScope?: RequestScope;
 }
 /**
  * Build a Reblu SITE API client. Each domain is a small namespace of bound
@@ -440,6 +444,7 @@ declare function createRebluClient(config: RebluClientConfig): {
         courses: (params?: AcademyCourseListParams, cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyCourseSummary>>;
         bySlug: (slug: string, cache?: RebluCachePolicy) => Promise<_reblu_site_contracts.AcademyCourseDetail>;
         lessonPreview: (courseSlug: string, lessonSlug: string) => Promise<_reblu_site_contracts.AcademyLessonPreview>;
+        instructors: (cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyInstructorPublic>>;
         categories: (cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyCategoryPublic>>;
         enrollmentRequest: (body: AcademyEnrollmentRequestInput, options?: RebluMutationOptions) => Promise<AcademyEnrollmentRequestResult>;
     };
@@ -456,4 +461,4 @@ declare function createRebluClient(config: RebluClientConfig): {
 /** The assembled client returned by {@link createRebluClient}. */
 type RebluClient = ReturnType<typeof createRebluClient>;
 
-export { type AcademyCourseListParams, type AcademyEnrollmentRequestInput, type AcademyEnrollmentRequestResult, AmbiguousPageSlugError, ApiError, type ApiErrorBody, type ApiErrorDetails, type BlogListParams, type ContactFormMetadata, type ContactFormMetadataOptions, DEFAULT_CHECKOUT_REDIRECT_HOSTS, type FeaturedPagesOptions, type ListResult, type PageBySlugOptions, type PageLocation, type PageSlugCandidate, type PagesListParams, PlainCacheAdapter, type RebluCacheAdapter, type RebluCachePolicy, type RebluClient, type RebluClientConfig, type RebluMutationOptions, type ShopProductsParams, type TrustBadgeListParams, UnsafeCheckoutRedirectError, VISITOR_IP_HEADER, buildContactFormMetadata, createRebluClient, currentPagePath, isSafeCheckoutRedirectUrl, visitorIpFromHeaders };
+export { type AcademyCourseListParams, type AcademyEnrollmentRequestInput, type AcademyEnrollmentRequestResult, AmbiguousPageSlugError, ApiError, type ApiErrorBody, type ApiErrorDetails, type BlogListParams, type ContactFormMetadata, type ContactFormMetadataOptions, DEFAULT_CHECKOUT_REDIRECT_HOSTS, type FeaturedPagesOptions, type ListResult, type PageBySlugOptions, type PageLocation, type PageSlugCandidate, type PagesListParams, PlainCacheAdapter, RETRY_AFTER_CAP_MS, type RebluCacheAdapter, type RebluCachePolicy, type RebluClient, type RebluClientConfig, type RebluMutationOptions, type RequestScope, type ShopProductsParams, type TrustBadgeListParams, UnsafeCheckoutRedirectError, VISITOR_IP_HEADER, buildContactFormMetadata, createRebluClient, currentPagePath, isSafeCheckoutRedirectUrl, visitorIpFromHeaders };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _reblu_site_contracts from '@reblu/site-contracts';
-import { AcademyCourseSort, PaginationMeta, PageType, PagesListSort, ShopSort, TrustBadgeType, ContactFormInput } from '@reblu/site-contracts';
+import { AcademyCourseListQuery, PaginationMeta, PageType, PagesListSort, ShopSort, TrustBadgeType, ContactFormInput } from '@reblu/site-contracts';
 
 /**
  * Cache adapter — the seam that severs the SDK from any framework's caching
@@ -91,28 +91,21 @@ interface ShopProductsParams {
 /**
  * Query params for `academy.courses` (REB-507), grounded on
  * `GET /api/site/academy/courses` — see `parseCourseListParams` in base-api.
+ * Since REB-547 this IS the documented query contract (`AcademyCourseListQuery`,
+ * the same keys the OpenAPI document lists), so the SDK cannot drift from it.
  *
  * Server-side clamping the caller should know about: `limit` is clamped to 1..50
  * and `page` to >= 1, so an out-of-range value is silently corrected rather than
- * rejected. `q`/`instructor`/`category` are truncated (200/64/120 chars).
- * `free: true` means "price is 0" and OVERRIDES any priceMin/priceMax range.
- * `sort` is a union because an unrecognized key is ignored server-side — typing
- * it makes a typo a compile error instead of a silent fall-back to default order.
+ * rejected. `q`/`category` are truncated (200/120 chars).
+ * - `category`: a `CourseCategory` slug. Only ACTIVE categories ever match.
+ * - `instructor`: a user id from `academy.instructors()`. A value that is not a
+ *   uuid matches no course.
+ * - `priceMin`/`priceMax`: inclusive, in integer cents.
+ * - `free: true` means "price is 0" and OVERRIDES any priceMin/priceMax range.
+ * - `sort` is a union because an unrecognized key is ignored server-side — typing
+ *   it makes a typo a compile error instead of a silent fall-back to default order.
  */
-interface AcademyCourseListParams {
-    page?: number;
-    limit?: number;
-    q?: string;
-    sort?: AcademyCourseSort;
-    /** A `CourseCategory` slug. Only ACTIVE categories ever match. */
-    category?: string;
-    /** A user id — `Course.instructorIds` is a denormalized user-uuid array. */
-    instructor?: string;
-    /** Restrict to free courses (priceCents = 0); overrides priceMin/priceMax. */
-    free?: boolean;
-    priceMin?: number;
-    priceMax?: number;
-}
+type AcademyCourseListParams = AcademyCourseListQuery;
 /**
  * Body of `academy.enrollmentRequest`, grounded on
  * `POST /api/site/academy/enrollment-requests`.
@@ -146,6 +139,10 @@ interface AcademyEnrollmentRequestResult {
     message: string;
 }
 
+/** Memo store of one server request, keyed by read identity (REB-1214). */
+type RequestScope = () => Map<string, Promise<unknown>> | undefined;
+/** Upper bound for a `Retry-After` wait before the single retry (REB-1214). */
+declare const RETRY_AFTER_CAP_MS = 2000;
 /**
  * Header carrying the visitor IP from a SITE server to base-api (REB-1005).
  * base-api keys its per-visitor limit on public writes on it, and trusts it
@@ -385,6 +382,13 @@ interface RebluClientConfig {
      * a Stripe CLI mock host) — never to widen production trust.
      */
     checkoutRedirectHosts?: string[];
+    /**
+     * REB-1214 — memo store of the current server request, so identical GET
+     * reads within it are fetched once. In Next.js pass `rebluRequestScope`
+     * from `@reblu/site-next` (React `cache()`); see the README. Without it,
+     * identical GETs share one fetch only while in flight.
+     */
+    requestScope?: RequestScope;
 }
 /**
  * Build a Reblu SITE API client. Each domain is a small namespace of bound
@@ -440,6 +444,7 @@ declare function createRebluClient(config: RebluClientConfig): {
         courses: (params?: AcademyCourseListParams, cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyCourseSummary>>;
         bySlug: (slug: string, cache?: RebluCachePolicy) => Promise<_reblu_site_contracts.AcademyCourseDetail>;
         lessonPreview: (courseSlug: string, lessonSlug: string) => Promise<_reblu_site_contracts.AcademyLessonPreview>;
+        instructors: (cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyInstructorPublic>>;
         categories: (cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyCategoryPublic>>;
         enrollmentRequest: (body: AcademyEnrollmentRequestInput, options?: RebluMutationOptions) => Promise<AcademyEnrollmentRequestResult>;
     };
@@ -456,4 +461,4 @@ declare function createRebluClient(config: RebluClientConfig): {
 /** The assembled client returned by {@link createRebluClient}. */
 type RebluClient = ReturnType<typeof createRebluClient>;
 
-export { type AcademyCourseListParams, type AcademyEnrollmentRequestInput, type AcademyEnrollmentRequestResult, AmbiguousPageSlugError, ApiError, type ApiErrorBody, type ApiErrorDetails, type BlogListParams, type ContactFormMetadata, type ContactFormMetadataOptions, DEFAULT_CHECKOUT_REDIRECT_HOSTS, type FeaturedPagesOptions, type ListResult, type PageBySlugOptions, type PageLocation, type PageSlugCandidate, type PagesListParams, PlainCacheAdapter, type RebluCacheAdapter, type RebluCachePolicy, type RebluClient, type RebluClientConfig, type RebluMutationOptions, type ShopProductsParams, type TrustBadgeListParams, UnsafeCheckoutRedirectError, VISITOR_IP_HEADER, buildContactFormMetadata, createRebluClient, currentPagePath, isSafeCheckoutRedirectUrl, visitorIpFromHeaders };
+export { type AcademyCourseListParams, type AcademyEnrollmentRequestInput, type AcademyEnrollmentRequestResult, AmbiguousPageSlugError, ApiError, type ApiErrorBody, type ApiErrorDetails, type BlogListParams, type ContactFormMetadata, type ContactFormMetadataOptions, DEFAULT_CHECKOUT_REDIRECT_HOSTS, type FeaturedPagesOptions, type ListResult, type PageBySlugOptions, type PageLocation, type PageSlugCandidate, type PagesListParams, PlainCacheAdapter, RETRY_AFTER_CAP_MS, type RebluCacheAdapter, type RebluCachePolicy, type RebluClient, type RebluClientConfig, type RebluMutationOptions, type RequestScope, type ShopProductsParams, type TrustBadgeListParams, UnsafeCheckoutRedirectError, VISITOR_IP_HEADER, buildContactFormMetadata, createRebluClient, currentPagePath, isSafeCheckoutRedirectUrl, visitorIpFromHeaders };

package/dist/index.js

@@ -131,25 +131,87 @@ function apiErrorRawBody(error) {
 }
 
 // src/client.ts
+var RETRY_AFTER_CAP_MS = 2e3;
+var DEFAULT_RETRY_DELAY_MS = 250;
+var RETRYABLE_READ_STATUSES = /* @__PURE__ */ new Set([429, 503]);
+function retryDelayMs(header) {
+  if (header !== null && header.trim() !== "") {
+    const value = header.trim();
+    const seconds = /^\d+$/.test(value) ? Number(value) * 1e3 : NaN;
+    const ms = Number.isFinite(seconds) ? seconds : Date.parse(value) - Date.now();
+    if (Number.isFinite(ms)) return Math.min(Math.max(0, ms), RETRY_AFTER_CAP_MS);
+  }
+  return DEFAULT_RETRY_DELAY_MS;
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function request(ctx, path, opts) {
-  const url = ctx.baseUrl + path;
+  const method = opts.method ?? "GET";
+  const init = {
+    method,
+    body: opts.body,
+    headers: {
+      "X-Reblu-Api-Key": ctx.apiKey,
+      "X-Reblu-Api-Version": ctx.apiVersion,
+      "Content-Type": "application/json",
+      ...opts.headers
+    },
+    ...ctx.cache.resolveRequestInit(opts.cachePolicy ?? {})
+  };
+  if (method !== "GET" || opts.body !== void 0) {
+    return attempt(ctx, path, init);
+  }
+  const key = JSON.stringify([ctx.baseUrl + path, init]);
+  const scope = ctx.requestScope?.();
+  const store = scope ?? ctx.inFlight;
+  const existing = store?.get(key);
+  if (existing) return existing;
+  const pending = readWithRetry(ctx, path, init);
+  if (store) {
+    store.set(key, pending);
+    pending.then(
+      () => {
+        if (!scope) store.delete(key);
+      },
+      () => {
+        if (store.get(key) === pending) store.delete(key);
+      }
+    );
+  }
+  return pending;
+}
+async function readWithRetry(ctx, path, init) {
+  try {
+    return await attempt(ctx, path, init);
+  } catch (error) {
+    if (!(error instanceof RetryableReadError)) throw error;
+    await sleep(retryDelayMs(error.retryAfter));
+    try {
+      return await attempt(ctx, path, init);
+    } catch (retryError) {
+      throw retryError instanceof RetryableReadError ? retryError.apiError : retryError;
+    }
+  }
+}
+var RetryableReadError = class extends Error {
+  constructor(apiError, retryAfter) {
+    super(apiError.message);
+    this.apiError = apiError;
+    this.retryAfter = retryAfter;
+  }
+  apiError;
+  retryAfter;
+};
+async function attempt(ctx, path, init) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), ctx.timeoutMs);
   try {
-    const res = await ctx.fetch(url, {
-      method: opts.method ?? "GET",
-      body: opts.body,
-      signal: controller.signal,
-      headers: {
-        "X-Reblu-Api-Key": ctx.apiKey,
-        "X-Reblu-Api-Version": ctx.apiVersion,
-        "Content-Type": "application/json",
-        ...opts.headers
-      },
-      ...ctx.cache.resolveRequestInit(opts.cachePolicy ?? {})
-    });
+    const res = await ctx.fetch(ctx.baseUrl + path, { ...init, signal: controller.signal });
     if (!res.ok) {
-      throw new ApiError(res.status, path, await res.text());
+      const error = new ApiError(res.status, path, await res.text());
+      if (init.method === "GET" && RETRYABLE_READ_STATUSES.has(res.status)) {
+        throw new RetryableReadError(error, res.headers.get("retry-after"));
+      }
+      throw error;
     }
     return await res.json();
   } finally {
@@ -220,6 +282,14 @@ function makeAcademyNamespace(ctx) {
       `/api/site/academy/courses/${encodeURIComponent(courseSlug)}/lessons/${encodeURIComponent(lessonSlug)}`,
       { cachePolicy: { revalidate: false } }
     ),
+    /**
+     * Instructors of published courses, sorted by name, backing the catalog
+     * instructor filter (REB-547). Pass an `id` as `courses({ instructor })`.
+     * Not paginated.
+     */
+    instructors: (cache) => requestList(ctx, "/api/site/academy/instructors", {
+      cachePolicy: cache
+    }),
     /** Active course categories backing the catalog filter. Not paginated. */
     categories: (cache) => requestList(ctx, "/api/site/academy/categories", {
       cachePolicy: cache
@@ -529,7 +599,9 @@ function createRebluClient(config) {
     cache: config.cache ?? new PlainCacheAdapter(),
     timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     fetch: boundFetch,
-    checkoutRedirectHosts: config.checkoutRedirectHosts ?? DEFAULT_CHECKOUT_REDIRECT_HOSTS
+    checkoutRedirectHosts: config.checkoutRedirectHosts ?? DEFAULT_CHECKOUT_REDIRECT_HOSTS,
+    requestScope: config.requestScope,
+    inFlight: /* @__PURE__ */ new Map()
   };
   return {
     config: makeConfigNamespace(ctx),
@@ -547,6 +619,6 @@ function createRebluClient(config) {
   };
 }
 
-export { AmbiguousPageSlugError, ApiError, DEFAULT_CHECKOUT_REDIRECT_HOSTS, PlainCacheAdapter, UnsafeCheckoutRedirectError, VISITOR_IP_HEADER, buildContactFormMetadata, createRebluClient, currentPagePath, isSafeCheckoutRedirectUrl, visitorIpFromHeaders };
+export { AmbiguousPageSlugError, ApiError, DEFAULT_CHECKOUT_REDIRECT_HOSTS, PlainCacheAdapter, RETRY_AFTER_CAP_MS, UnsafeCheckoutRedirectError, VISITOR_IP_HEADER, buildContactFormMetadata, createRebluClient, currentPagePath, isSafeCheckoutRedirectUrl, visitorIpFromHeaders };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map