@reblu/site-client 5.8.0 → 5.10.0

package/dist/index.d.cts

@@ -1,6 +1,35 @@
 import * as _reblu_site_contracts from '@reblu/site-contracts';
 import { AcademyCourseSort, PaginationMeta, PageType, PagesListSort, ShopSort, TrustBadgeType } from '@reblu/site-contracts';
 
+/**
+ * Cache adapter — the seam that severs the SDK from any framework's caching
+ * model (design doc D4 / §3.2). The client owns *when* to cache (a per-call
+ * `RebluCachePolicy`); the adapter owns *how* (the framework-specific
+ * `RequestInit` fields). `@reblu/site-client` ships the framework-agnostic
+ * `PlainCacheAdapter`; `@reblu/site-next` (REB-418) supplies a `NextCacheAdapter`
+ * that returns `{ next: { revalidate } }`.
+ */
+interface RebluCachePolicy {
+    /**
+     * Seconds to revalidate. `undefined` → use the adapter's default; `0`/`false`
+     * → never cache (always fetch fresh).
+     */
+    revalidate?: number | false;
+}
+interface RebluCacheAdapter {
+    /** Map a per-call cache policy to framework-specific `fetch` `RequestInit` fields. */
+    resolveRequestInit(policy: RebluCachePolicy): RequestInit;
+}
+/**
+ * Default adapter — plain `fetch` cache semantics that work in Node, edge,
+ * browser and tests. No `next`, no `server-only`.
+ */
+declare class PlainCacheAdapter implements RebluCacheAdapter {
+    private readonly defaultRevalidate;
+    constructor(defaultRevalidate?: number | false);
+    resolveRequestInit(policy: RebluCachePolicy): RequestInit;
+}
+
 /**
  * The shape every list method returns. Unlike demo-site's old bare-array return,
  * the SDK surfaces `meta` so pagination is never silently dropped (design doc
@@ -118,33 +147,31 @@ interface AcademyEnrollmentRequestResult {
 }
 
 /**
- * Cache adapter — the seam that severs the SDK from any framework's caching
- * model (design doc D4 / §3.2). The client owns *when* to cache (a per-call
- * `RebluCachePolicy`); the adapter owns *how* (the framework-specific
- * `RequestInit` fields). `@reblu/site-client` ships the framework-agnostic
- * `PlainCacheAdapter`; `@reblu/site-next` (REB-418) supplies a `NextCacheAdapter`
- * that returns `{ next: { revalidate } }`.
+ * 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
+ * only behind a valid API key.
  */
-interface RebluCachePolicy {
-    /**
-     * Seconds to revalidate. `undefined` → use the adapter's default; `0`/`false`
-     * → never cache (always fetch fresh).
-     */
-    revalidate?: number | false;
-}
-interface RebluCacheAdapter {
-    /** Map a per-call cache policy to framework-specific `fetch` `RequestInit` fields. */
-    resolveRequestInit(policy: RebluCachePolicy): RequestInit;
-}
+declare const VISITOR_IP_HEADER = "x-reblu-visitor-ip";
 /**
- * Default adapter — plain `fetch` cache semantics that work in Node, edge,
- * browser and tests. No `next`, no `server-only`.
+ * Per-call options for a write (REB-1005).
+ *
+ * - `visitorIp` — the visitor's IP when a SITE calls the SDK server-side, sent
+ *   as `x-reblu-visitor-ip`. Do NOT rely on forwarding `x-forwarded-for`: on
+ *   Vercel the SITE→base-api hop gets it overwritten with the SITE function's
+ *   egress IP. Read it from the INCOMING request with
+ *   {@link visitorIpFromHeaders}.
+ * - `headers` — other extra headers (e.g. `user-agent`). They can never set
+ *   `x-reblu-visitor-ip` nor replace `X-Reblu-Api-Key`, `X-Reblu-Api-Version`
+ *   or `Content-Type`.
  */
-declare class PlainCacheAdapter implements RebluCacheAdapter {
-    private readonly defaultRevalidate;
-    constructor(defaultRevalidate?: number | false);
-    resolveRequestInit(policy: RebluCachePolicy): RequestInit;
+interface RebluMutationOptions {
+    visitorIp?: string;
+    headers?: Record<string, string>;
 }
+/** The visitor IP of an incoming request: first `x-forwarded-for` entry, else `x-real-ip`. */
+declare function visitorIpFromHeaders(headers: {
+    get(name: string): string | null;
+}): string | undefined;
 
 /**
  * The `details` shape `/api/site/contact-form` and `/api/site/leads` attach on a
@@ -364,26 +391,26 @@ declare function createRebluClient(config: RebluClientConfig): {
         checkout: (body: _reblu_site_contracts.ShopCheckoutInput) => Promise<_reblu_site_contracts.ShopCheckoutSession>;
         validateCart: (body: _reblu_site_contracts.ShopValidateCartInput) => Promise<_reblu_site_contracts.ShopCartValidation>;
         applyDiscount: (body: _reblu_site_contracts.ShopApplyDiscountInput) => Promise<_reblu_site_contracts.ShopDiscountApplication>;
-        checkEmail: (body: _reblu_site_contracts.ShopCheckEmailInput) => Promise<_reblu_site_contracts.ShopEmailCheck>;
+        checkEmail: (body: _reblu_site_contracts.ShopCheckEmailInput, options?: RebluMutationOptions) => Promise<_reblu_site_contracts.ShopEmailCheck>;
         order: (sessionId: string, cache?: RebluCachePolicy) => Promise<_reblu_site_contracts.ShopOrder>;
     };
     academy: {
         courses: (params?: AcademyCourseListParams, cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyCourseSummary>>;
         bySlug: (slug: string, cache?: RebluCachePolicy) => Promise<_reblu_site_contracts.AcademyCourseDetail>;
         categories: (cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyCategoryPublic>>;
-        enrollmentRequest: (body: AcademyEnrollmentRequestInput) => Promise<AcademyEnrollmentRequestResult>;
+        enrollmentRequest: (body: AcademyEnrollmentRequestInput, options?: RebluMutationOptions) => Promise<AcademyEnrollmentRequestResult>;
     };
     contactForm: {
-        submit: (body: _reblu_site_contracts.ContactFormInput) => Promise<_reblu_site_contracts.ContactFormSubmission>;
+        submit: (body: _reblu_site_contracts.ContactFormInput, options?: RebluMutationOptions) => Promise<_reblu_site_contracts.ContactFormSubmission>;
     };
     leads: {
         create: (body: _reblu_site_contracts.LeadInput) => Promise<_reblu_site_contracts.LeadSubmission>;
     };
     dataRequests: {
-        submit: (body: _reblu_site_contracts.DataRequestInput) => Promise<_reblu_site_contracts.DataRequestSubmission>;
+        submit: (body: _reblu_site_contracts.DataRequestInput, options?: RebluMutationOptions) => Promise<_reblu_site_contracts.DataRequestSubmission>;
     };
 };
 /** 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, DEFAULT_CHECKOUT_REDIRECT_HOSTS, type FeaturedPagesOptions, type ListResult, type PageBySlugOptions, type PageSlugCandidate, type PagesListParams, PlainCacheAdapter, type RebluCacheAdapter, type RebluCachePolicy, type RebluClient, type RebluClientConfig, type ShopProductsParams, type TrustBadgeListParams, UnsafeCheckoutRedirectError, createRebluClient, isSafeCheckoutRedirectUrl };
+export { type AcademyCourseListParams, type AcademyEnrollmentRequestInput, type AcademyEnrollmentRequestResult, AmbiguousPageSlugError, ApiError, type ApiErrorBody, type ApiErrorDetails, type BlogListParams, DEFAULT_CHECKOUT_REDIRECT_HOSTS, type FeaturedPagesOptions, type ListResult, type PageBySlugOptions, type PageSlugCandidate, type PagesListParams, PlainCacheAdapter, type RebluCacheAdapter, type RebluCachePolicy, type RebluClient, type RebluClientConfig, type RebluMutationOptions, type ShopProductsParams, type TrustBadgeListParams, UnsafeCheckoutRedirectError, VISITOR_IP_HEADER, createRebluClient, isSafeCheckoutRedirectUrl, visitorIpFromHeaders };

package/dist/index.d.ts

@@ -1,6 +1,35 @@
 import * as _reblu_site_contracts from '@reblu/site-contracts';
 import { AcademyCourseSort, PaginationMeta, PageType, PagesListSort, ShopSort, TrustBadgeType } from '@reblu/site-contracts';
 
+/**
+ * Cache adapter — the seam that severs the SDK from any framework's caching
+ * model (design doc D4 / §3.2). The client owns *when* to cache (a per-call
+ * `RebluCachePolicy`); the adapter owns *how* (the framework-specific
+ * `RequestInit` fields). `@reblu/site-client` ships the framework-agnostic
+ * `PlainCacheAdapter`; `@reblu/site-next` (REB-418) supplies a `NextCacheAdapter`
+ * that returns `{ next: { revalidate } }`.
+ */
+interface RebluCachePolicy {
+    /**
+     * Seconds to revalidate. `undefined` → use the adapter's default; `0`/`false`
+     * → never cache (always fetch fresh).
+     */
+    revalidate?: number | false;
+}
+interface RebluCacheAdapter {
+    /** Map a per-call cache policy to framework-specific `fetch` `RequestInit` fields. */
+    resolveRequestInit(policy: RebluCachePolicy): RequestInit;
+}
+/**
+ * Default adapter — plain `fetch` cache semantics that work in Node, edge,
+ * browser and tests. No `next`, no `server-only`.
+ */
+declare class PlainCacheAdapter implements RebluCacheAdapter {
+    private readonly defaultRevalidate;
+    constructor(defaultRevalidate?: number | false);
+    resolveRequestInit(policy: RebluCachePolicy): RequestInit;
+}
+
 /**
  * The shape every list method returns. Unlike demo-site's old bare-array return,
  * the SDK surfaces `meta` so pagination is never silently dropped (design doc
@@ -118,33 +147,31 @@ interface AcademyEnrollmentRequestResult {
 }
 
 /**
- * Cache adapter — the seam that severs the SDK from any framework's caching
- * model (design doc D4 / §3.2). The client owns *when* to cache (a per-call
- * `RebluCachePolicy`); the adapter owns *how* (the framework-specific
- * `RequestInit` fields). `@reblu/site-client` ships the framework-agnostic
- * `PlainCacheAdapter`; `@reblu/site-next` (REB-418) supplies a `NextCacheAdapter`
- * that returns `{ next: { revalidate } }`.
+ * 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
+ * only behind a valid API key.
  */
-interface RebluCachePolicy {
-    /**
-     * Seconds to revalidate. `undefined` → use the adapter's default; `0`/`false`
-     * → never cache (always fetch fresh).
-     */
-    revalidate?: number | false;
-}
-interface RebluCacheAdapter {
-    /** Map a per-call cache policy to framework-specific `fetch` `RequestInit` fields. */
-    resolveRequestInit(policy: RebluCachePolicy): RequestInit;
-}
+declare const VISITOR_IP_HEADER = "x-reblu-visitor-ip";
 /**
- * Default adapter — plain `fetch` cache semantics that work in Node, edge,
- * browser and tests. No `next`, no `server-only`.
+ * Per-call options for a write (REB-1005).
+ *
+ * - `visitorIp` — the visitor's IP when a SITE calls the SDK server-side, sent
+ *   as `x-reblu-visitor-ip`. Do NOT rely on forwarding `x-forwarded-for`: on
+ *   Vercel the SITE→base-api hop gets it overwritten with the SITE function's
+ *   egress IP. Read it from the INCOMING request with
+ *   {@link visitorIpFromHeaders}.
+ * - `headers` — other extra headers (e.g. `user-agent`). They can never set
+ *   `x-reblu-visitor-ip` nor replace `X-Reblu-Api-Key`, `X-Reblu-Api-Version`
+ *   or `Content-Type`.
  */
-declare class PlainCacheAdapter implements RebluCacheAdapter {
-    private readonly defaultRevalidate;
-    constructor(defaultRevalidate?: number | false);
-    resolveRequestInit(policy: RebluCachePolicy): RequestInit;
+interface RebluMutationOptions {
+    visitorIp?: string;
+    headers?: Record<string, string>;
 }
+/** The visitor IP of an incoming request: first `x-forwarded-for` entry, else `x-real-ip`. */
+declare function visitorIpFromHeaders(headers: {
+    get(name: string): string | null;
+}): string | undefined;
 
 /**
  * The `details` shape `/api/site/contact-form` and `/api/site/leads` attach on a
@@ -364,26 +391,26 @@ declare function createRebluClient(config: RebluClientConfig): {
         checkout: (body: _reblu_site_contracts.ShopCheckoutInput) => Promise<_reblu_site_contracts.ShopCheckoutSession>;
         validateCart: (body: _reblu_site_contracts.ShopValidateCartInput) => Promise<_reblu_site_contracts.ShopCartValidation>;
         applyDiscount: (body: _reblu_site_contracts.ShopApplyDiscountInput) => Promise<_reblu_site_contracts.ShopDiscountApplication>;
-        checkEmail: (body: _reblu_site_contracts.ShopCheckEmailInput) => Promise<_reblu_site_contracts.ShopEmailCheck>;
+        checkEmail: (body: _reblu_site_contracts.ShopCheckEmailInput, options?: RebluMutationOptions) => Promise<_reblu_site_contracts.ShopEmailCheck>;
         order: (sessionId: string, cache?: RebluCachePolicy) => Promise<_reblu_site_contracts.ShopOrder>;
     };
     academy: {
         courses: (params?: AcademyCourseListParams, cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyCourseSummary>>;
         bySlug: (slug: string, cache?: RebluCachePolicy) => Promise<_reblu_site_contracts.AcademyCourseDetail>;
         categories: (cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.AcademyCategoryPublic>>;
-        enrollmentRequest: (body: AcademyEnrollmentRequestInput) => Promise<AcademyEnrollmentRequestResult>;
+        enrollmentRequest: (body: AcademyEnrollmentRequestInput, options?: RebluMutationOptions) => Promise<AcademyEnrollmentRequestResult>;
     };
     contactForm: {
-        submit: (body: _reblu_site_contracts.ContactFormInput) => Promise<_reblu_site_contracts.ContactFormSubmission>;
+        submit: (body: _reblu_site_contracts.ContactFormInput, options?: RebluMutationOptions) => Promise<_reblu_site_contracts.ContactFormSubmission>;
     };
     leads: {
         create: (body: _reblu_site_contracts.LeadInput) => Promise<_reblu_site_contracts.LeadSubmission>;
     };
     dataRequests: {
-        submit: (body: _reblu_site_contracts.DataRequestInput) => Promise<_reblu_site_contracts.DataRequestSubmission>;
+        submit: (body: _reblu_site_contracts.DataRequestInput, options?: RebluMutationOptions) => Promise<_reblu_site_contracts.DataRequestSubmission>;
     };
 };
 /** 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, DEFAULT_CHECKOUT_REDIRECT_HOSTS, type FeaturedPagesOptions, type ListResult, type PageBySlugOptions, type PageSlugCandidate, type PagesListParams, PlainCacheAdapter, type RebluCacheAdapter, type RebluCachePolicy, type RebluClient, type RebluClientConfig, type ShopProductsParams, type TrustBadgeListParams, UnsafeCheckoutRedirectError, createRebluClient, isSafeCheckoutRedirectUrl };
+export { type AcademyCourseListParams, type AcademyEnrollmentRequestInput, type AcademyEnrollmentRequestResult, AmbiguousPageSlugError, ApiError, type ApiErrorBody, type ApiErrorDetails, type BlogListParams, DEFAULT_CHECKOUT_REDIRECT_HOSTS, type FeaturedPagesOptions, type ListResult, type PageBySlugOptions, type PageSlugCandidate, type PagesListParams, PlainCacheAdapter, type RebluCacheAdapter, type RebluCachePolicy, type RebluClient, type RebluClientConfig, type RebluMutationOptions, type ShopProductsParams, type TrustBadgeListParams, UnsafeCheckoutRedirectError, VISITOR_IP_HEADER, createRebluClient, isSafeCheckoutRedirectUrl, visitorIpFromHeaders };

package/dist/index.js

@@ -164,11 +164,33 @@ async function requestList(ctx, path, opts) {
   const body = await request(ctx, path, opts);
   return { data: body.data, meta: body.meta };
 }
-async function requestMutation(ctx, path, body) {
+var VISITOR_IP_HEADER = "x-reblu-visitor-ip";
+function visitorIpFromHeaders(headers) {
+  return headers.get("x-forwarded-for")?.split(",")[0]?.trim() || headers.get("x-real-ip")?.trim() || void 0;
+}
+var RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-reblu-api-key",
+  "x-reblu-api-version",
+  "content-type",
+  VISITOR_IP_HEADER
+]);
+function extraHeaders(options) {
+  if (!options?.headers && !options?.visitorIp) return void 0;
+  const safe = {};
+  for (const [name, value] of Object.entries(options.headers ?? {})) {
+    if (!RESERVED_HEADERS.has(name.toLowerCase())) safe[name] = value;
+  }
+  const visitorIp = options.visitorIp?.trim();
+  if (visitorIp) safe[VISITOR_IP_HEADER] = visitorIp;
+  return safe;
+}
+async function requestMutation(ctx, path, body, options) {
+  const headers = extraHeaders(options);
   const envelope = await request(ctx, path, {
     method: "POST",
     body: JSON.stringify(body),
-    cachePolicy: { revalidate: false }
+    cachePolicy: { revalidate: false },
+    ...headers ? { headers } : {}
   });
   return envelope.data;
 }
@@ -197,12 +219,21 @@ function makeAcademyNamespace(ctx) {
      * was new (a request row was created) or already known (a sign-in link was
      * sent and NO request row exists). Never present the returned message as
      * confirmation that a request was recorded — it is not one.
+     *
+     * Server-side, pass `options.visitorIp` (from the incoming request, see
+     * `visitorIpFromHeaders`): base-api keys this route's per-IP limit on it
+     * and, without it, throttles every visitor of the SITE in one shared
+     * tenant-level bucket (REB-1006).
      */
-    enrollmentRequest: (body) => request(ctx, "/api/site/academy/enrollment-requests", {
-      method: "POST",
-      body: JSON.stringify(body),
-      cachePolicy: { revalidate: false }
-    })
+    enrollmentRequest: (body, options) => {
+      const headers = extraHeaders(options);
+      return request(ctx, "/api/site/academy/enrollment-requests", {
+        method: "POST",
+        body: JSON.stringify(body),
+        cachePolicy: { revalidate: false },
+        ...headers ? { headers } : {}
+      });
+    }
   };
 }
 
@@ -242,8 +273,18 @@ function makeConfigNamespace(ctx) {
 // src/domains/contact-form.ts
 function makeContactFormNamespace(ctx) {
   return {
-    /** Submit a contact form. Returns the created lead acknowledgement. */
-    submit: (body) => requestMutation(ctx, "/api/site/contact-form", body)
+    /**
+     * Submit a contact form. Returns the created lead acknowledgement.
+     * Server-side (a Server Action / Route Handler), pass `options.visitorIp`
+     * (from the incoming request, see `visitorIpFromHeaders`) so base-api's
+     * per-IP limit (REB-1005) applies to the real visitor.
+     */
+    submit: (body, options) => requestMutation(
+      ctx,
+      "/api/site/contact-form",
+      body,
+      options
+    )
   };
 }
 
@@ -257,11 +298,17 @@ function makeCtasNamespace(ctx) {
 // src/domains/data-requests.ts
 function makeDataRequestsNamespace(ctx) {
   return {
-    /** Submit a data-subject request. Returns its acknowledgement with the 72h deadline. */
-    submit: (body) => requestMutation(
+    /**
+     * Submit a data-subject request. Returns its acknowledgement with the 72h
+     * deadline. Server-side, pass `options.visitorIp` (from the incoming
+     * request, see `visitorIpFromHeaders`) so base-api's per-IP limit
+     * (REB-1005) sees the real visitor.
+     */
+    submit: (body, options) => requestMutation(
       ctx,
       "/api/site/data-requests",
-      body
+      body,
+      options
     )
   };
 }
@@ -399,8 +446,18 @@ function makeShopNamespace(ctx) {
      * branch UI on `exists`; the checkout always offers «Iniciar sesión o
      * continuar como invitado» and the server links the order to an existing
      * account after payment. Removed in the next major.
+     *
+     * Server-side, pass `options.visitorIp` (from the incoming request, see
+     * `visitorIpFromHeaders`): base-api keys this route's per-IP limit on it
+     * and, without it, throttles every visitor of the SITE in one shared
+     * tenant-level bucket (REB-1006).
      */
-    checkEmail: (body) => requestMutation(ctx, "/api/site/shop/check-email", body),
+    checkEmail: (body, options) => requestMutation(
+      ctx,
+      "/api/site/shop/check-email",
+      body,
+      options
+    ),
     /**
      * Look up a confirmed (or still-pending) order by its Stripe Checkout
      * session id — the order-confirmation flow (REB-829). `GET`, so it goes
@@ -459,6 +516,6 @@ function createRebluClient(config) {
   };
 }
 
-export { AmbiguousPageSlugError, ApiError, DEFAULT_CHECKOUT_REDIRECT_HOSTS, PlainCacheAdapter, UnsafeCheckoutRedirectError, createRebluClient, isSafeCheckoutRedirectUrl };
+export { AmbiguousPageSlugError, ApiError, DEFAULT_CHECKOUT_REDIRECT_HOSTS, PlainCacheAdapter, UnsafeCheckoutRedirectError, VISITOR_IP_HEADER, createRebluClient, isSafeCheckoutRedirectUrl, visitorIpFromHeaders };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map