@reblu/site-client 5.7.0 → 5.9.0

package/dist/index.d.cts

@@ -1,5 +1,34 @@
 import * as _reblu_site_contracts from '@reblu/site-contracts';
-import { AcademyCourseSort, PaginationMeta, PageType, PagesListSort, ShopSort } 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,
@@ -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
@@ -257,6 +284,12 @@ interface FeaturedPagesOptions {
     cache?: RebluCachePolicy;
 }
 
+/** Filters for {@link makeTrustBadgesNamespace}'s `list` (REB-996). */
+interface TrustBadgeListParams {
+    /** Only badges of this type (e.g. `'SUBVENTION'`). Omit for every type. */
+    type?: TrustBadgeType;
+}
+
 /**
  * Stripe Checkout redirect-origin guard (REB-836, defence in depth).
  *
@@ -327,7 +360,10 @@ declare function createRebluClient(config: RebluClientConfig): {
         get: (cache?: RebluCachePolicy) => Promise<_reblu_site_contracts.Legal>;
     };
     trustBadges: {
-        list: (cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.TrustBadge>>;
+        list: {
+            (cache?: RebluCachePolicy): Promise<ListResult<_reblu_site_contracts.TrustBadge>>;
+            (params: TrustBadgeListParams, cache?: RebluCachePolicy): Promise<ListResult<_reblu_site_contracts.TrustBadge>>;
+        };
     };
     ctas: {
         list: (slot: string, cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.Cta>>;
@@ -365,13 +401,16 @@ declare function createRebluClient(config: RebluClientConfig): {
         enrollmentRequest: (body: AcademyEnrollmentRequestInput) => 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, 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, 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,5 +1,34 @@
 import * as _reblu_site_contracts from '@reblu/site-contracts';
-import { AcademyCourseSort, PaginationMeta, PageType, PagesListSort, ShopSort } 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,
@@ -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
@@ -257,6 +284,12 @@ interface FeaturedPagesOptions {
     cache?: RebluCachePolicy;
 }
 
+/** Filters for {@link makeTrustBadgesNamespace}'s `list` (REB-996). */
+interface TrustBadgeListParams {
+    /** Only badges of this type (e.g. `'SUBVENTION'`). Omit for every type. */
+    type?: TrustBadgeType;
+}
+
 /**
  * Stripe Checkout redirect-origin guard (REB-836, defence in depth).
  *
@@ -327,7 +360,10 @@ declare function createRebluClient(config: RebluClientConfig): {
         get: (cache?: RebluCachePolicy) => Promise<_reblu_site_contracts.Legal>;
     };
     trustBadges: {
-        list: (cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.TrustBadge>>;
+        list: {
+            (cache?: RebluCachePolicy): Promise<ListResult<_reblu_site_contracts.TrustBadge>>;
+            (params: TrustBadgeListParams, cache?: RebluCachePolicy): Promise<ListResult<_reblu_site_contracts.TrustBadge>>;
+        };
     };
     ctas: {
         list: (slot: string, cache?: RebluCachePolicy) => Promise<ListResult<_reblu_site_contracts.Cta>>;
@@ -365,13 +401,16 @@ declare function createRebluClient(config: RebluClientConfig): {
         enrollmentRequest: (body: AcademyEnrollmentRequestInput) => 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, 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, 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;
 }
@@ -242,8 +264,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
+    )
   };
 }
 
@@ -254,6 +286,24 @@ function makeCtasNamespace(ctx) {
   };
 }
 
+// src/domains/data-requests.ts
+function makeDataRequestsNamespace(ctx) {
+  return {
+    /**
+     * 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,
+      options
+    )
+  };
+}
+
 // src/domains/leads.ts
 function makeLeadsNamespace(ctx) {
   return {
@@ -401,10 +451,20 @@ function makeShopNamespace(ctx) {
 }
 
 // src/domains/trust-badges.ts
+function isCachePolicy(value) {
+  return Object.prototype.hasOwnProperty.call(value, "revalidate");
+}
 function makeTrustBadgesNamespace(ctx) {
-  return {
-    list: (cache) => requestList(ctx, "/api/site/trust-badges", { cachePolicy: cache })
-  };
+  function list(paramsOrCache, cache) {
+    const legacyCache = paramsOrCache && isCachePolicy(paramsOrCache) ? paramsOrCache : void 0;
+    const params = legacyCache ? void 0 : paramsOrCache;
+    return requestList(
+      ctx,
+      buildUrl("/api/site/trust-badges", { type: params?.type }),
+      { cachePolicy: legacyCache ?? cache }
+    );
+  }
+  return { list };
 }
 
 // src/index.ts
@@ -432,10 +492,11 @@ function createRebluClient(config) {
     shop: makeShopNamespace(ctx),
     academy: makeAcademyNamespace(ctx),
     contactForm: makeContactFormNamespace(ctx),
-    leads: makeLeadsNamespace(ctx)
+    leads: makeLeadsNamespace(ctx),
+    dataRequests: makeDataRequestsNamespace(ctx)
   };
 }
 
-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