perspectapi-ts-sdk 6.4.0 → 6.5.0

package/dist/index.d.mts

@@ -1967,7 +1967,7 @@ declare class SiteUsersV2Client extends BaseV2Client {
     /** Update the authenticated user's own fields. */
     updateMe(siteName: string, data: V2SiteUserMeUpdateParams): Promise<V2SiteUser>;
     /** Fetch the profile KV map as a dedicated `site_user_profile` envelope. */
-    getProfile(siteName: string): Promise<V2SiteUserProfile>;
+    getProfile(siteName: string, cachePolicy?: CachePolicy): Promise<V2SiteUserProfile>;
     /**
      * Set a single profile key. The value is persisted verbatim — callers wanting
      * structured data should JSON-stringify their value first.
@@ -2104,7 +2104,7 @@ declare class WebhooksV2Client extends BaseV2Client {
 
 declare class SubscriptionsV2Client extends BaseV2Client {
     /** List all subscriptions for the authenticated user. */
-    listMySubscriptions(siteName: string): Promise<V2List<V2SiteUserSubscription>>;
+    listMySubscriptions(siteName: string, cachePolicy?: CachePolicy): Promise<V2List<V2SiteUserSubscription>>;
     /** Pause a subscription. */
     pauseSubscription(siteName: string, subId: string, params?: V2SubscriptionPauseParams): Promise<V2SiteUserSubscription>;
     /** Resume a paused subscription. */
@@ -2114,7 +2114,7 @@ declare class SubscriptionsV2Client extends BaseV2Client {
     /** Change the plan (price) of a subscription. */
     changeSubscriptionPlan(siteName: string, subId: string, params: V2SubscriptionChangePlanParams): Promise<V2SiteUserSubscription>;
     /** List subscriptions for a specific user (admin). */
-    listUserSubscriptions(siteName: string, userId: string): Promise<V2List<V2SiteUserSubscription>>;
+    listUserSubscriptions(siteName: string, userId: string, cachePolicy?: CachePolicy): Promise<V2List<V2SiteUserSubscription>>;
     /** Pause a user's subscription (admin). */
     pauseUserSubscription(siteName: string, userId: string, subId: string, params?: V2SubscriptionPauseParams): Promise<V2SiteUserSubscription>;
     /** Resume a user's paused subscription (admin). */

package/dist/index.d.ts

@@ -1967,7 +1967,7 @@ declare class SiteUsersV2Client extends BaseV2Client {
     /** Update the authenticated user's own fields. */
     updateMe(siteName: string, data: V2SiteUserMeUpdateParams): Promise<V2SiteUser>;
     /** Fetch the profile KV map as a dedicated `site_user_profile` envelope. */
-    getProfile(siteName: string): Promise<V2SiteUserProfile>;
+    getProfile(siteName: string, cachePolicy?: CachePolicy): Promise<V2SiteUserProfile>;
     /**
      * Set a single profile key. The value is persisted verbatim — callers wanting
      * structured data should JSON-stringify their value first.
@@ -2104,7 +2104,7 @@ declare class WebhooksV2Client extends BaseV2Client {
 
 declare class SubscriptionsV2Client extends BaseV2Client {
     /** List all subscriptions for the authenticated user. */
-    listMySubscriptions(siteName: string): Promise<V2List<V2SiteUserSubscription>>;
+    listMySubscriptions(siteName: string, cachePolicy?: CachePolicy): Promise<V2List<V2SiteUserSubscription>>;
     /** Pause a subscription. */
     pauseSubscription(siteName: string, subId: string, params?: V2SubscriptionPauseParams): Promise<V2SiteUserSubscription>;
     /** Resume a paused subscription. */
@@ -2114,7 +2114,7 @@ declare class SubscriptionsV2Client extends BaseV2Client {
     /** Change the plan (price) of a subscription. */
     changeSubscriptionPlan(siteName: string, subId: string, params: V2SubscriptionChangePlanParams): Promise<V2SiteUserSubscription>;
     /** List subscriptions for a specific user (admin). */
-    listUserSubscriptions(siteName: string, userId: string): Promise<V2List<V2SiteUserSubscription>>;
+    listUserSubscriptions(siteName: string, userId: string, cachePolicy?: CachePolicy): Promise<V2List<V2SiteUserSubscription>>;
     /** Pause a user's subscription (admin). */
     pauseUserSubscription(siteName: string, userId: string, subId: string, params?: V2SubscriptionPauseParams): Promise<V2SiteUserSubscription>;
     /** Resume a user's paused subscription (admin). */

package/dist/index.js

@@ -1038,9 +1038,11 @@ var SiteUsersV2Client = class extends BaseV2Client {
     );
   }
   /** Fetch the profile KV map as a dedicated `site_user_profile` envelope. */
-  async getProfile(siteName) {
+  async getProfile(siteName, cachePolicy) {
     return this.getOne(
-      this.sitePath(siteName, "users", "me/profile")
+      this.sitePath(siteName, "users", "me/profile"),
+      void 0,
+      cachePolicy
     );
   }
   /**
@@ -1258,9 +1260,11 @@ var WebhooksV2Client = class extends BaseV2Client {
 var SubscriptionsV2Client = class extends BaseV2Client {
   // --- Authenticated "me" endpoints (site-user JWT) ---
   /** List all subscriptions for the authenticated user. */
-  async listMySubscriptions(siteName) {
+  async listMySubscriptions(siteName, cachePolicy) {
     return this.getList(
-      this.sitePath(siteName, "users", "me/subscriptions")
+      this.sitePath(siteName, "users", "me/subscriptions"),
+      void 0,
+      cachePolicy
     );
   }
   /** Pause a subscription. */
@@ -1292,9 +1296,11 @@ var SubscriptionsV2Client = class extends BaseV2Client {
   }
   // --- Admin endpoints (API key) ---
   /** List subscriptions for a specific user (admin). */
-  async listUserSubscriptions(siteName, userId) {
+  async listUserSubscriptions(siteName, userId, cachePolicy) {
     return this.getList(
-      this.sitePath(siteName, "users", `${userId}/subscriptions`)
+      this.sitePath(siteName, "users", `${userId}/subscriptions`),
+      void 0,
+      cachePolicy
     );
   }
   /** Pause a user's subscription (admin). */
@@ -4253,15 +4259,16 @@ function createPerspectAb(options) {
           `${VID_COOKIE}=${visitorId}; Path=/; Max-Age=${VID_COOKIE_MAX_AGE}; SameSite=Lax; Secure; HttpOnly`
         );
       }
+      const isBot = classifyBotFromCfRequest(request);
       const config = await getConfig(options.cache, apiKey, siteName, baseUrl);
-      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId), responseHeaders };
+      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId, isBot), responseHeaders };
     },
     async refreshConfig() {
       await fetchAndStoreConfig(options.cache, apiKey, siteName, baseUrl);
     }
   };
 }
-function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId) {
+function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId, isBot) {
   return {
     async getVariant(flagKey) {
       const flag = config.flags[flagKey];
@@ -4281,6 +4288,7 @@ function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId) {
         version: flag.currentVersion,
         variant: assigned,
         visitorId,
+        isBot,
         dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, "exposure"),
         ts: Math.floor(Date.now() / 1e3)
       });
@@ -4301,6 +4309,7 @@ function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId) {
           version: flag.currentVersion,
           variant: assigned,
           visitorId,
+          isBot,
           event,
           dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, event),
           ts: Math.floor(Date.now() / 1e3),
@@ -4339,6 +4348,13 @@ function emit(apiKey, baseUrl, ctx, body) {
   }).then(() => void 0).catch(() => void 0);
   if (ctx) ctx.waitUntil(task);
 }
+function classifyBotFromCfRequest(request) {
+  const cf = request.cf;
+  if (!cf?.botManagement) return false;
+  if (cf.botManagement.verifiedBot) return true;
+  if (typeof cf.botManagement.score === "number") return cf.botManagement.score < 30;
+  return false;
+}
 function readOrMintVid(request) {
   const cookie = request.headers.get("cookie") ?? "";
   const match = cookie.match(/(?:^|; )perspect_vid=([^;]+)/);

package/dist/index.mjs

@@ -962,9 +962,11 @@ var SiteUsersV2Client = class extends BaseV2Client {
     );
   }
   /** Fetch the profile KV map as a dedicated `site_user_profile` envelope. */
-  async getProfile(siteName) {
+  async getProfile(siteName, cachePolicy) {
     return this.getOne(
-      this.sitePath(siteName, "users", "me/profile")
+      this.sitePath(siteName, "users", "me/profile"),
+      void 0,
+      cachePolicy
     );
   }
   /**
@@ -1182,9 +1184,11 @@ var WebhooksV2Client = class extends BaseV2Client {
 var SubscriptionsV2Client = class extends BaseV2Client {
   // --- Authenticated "me" endpoints (site-user JWT) ---
   /** List all subscriptions for the authenticated user. */
-  async listMySubscriptions(siteName) {
+  async listMySubscriptions(siteName, cachePolicy) {
     return this.getList(
-      this.sitePath(siteName, "users", "me/subscriptions")
+      this.sitePath(siteName, "users", "me/subscriptions"),
+      void 0,
+      cachePolicy
     );
   }
   /** Pause a subscription. */
@@ -1216,9 +1220,11 @@ var SubscriptionsV2Client = class extends BaseV2Client {
   }
   // --- Admin endpoints (API key) ---
   /** List subscriptions for a specific user (admin). */
-  async listUserSubscriptions(siteName, userId) {
+  async listUserSubscriptions(siteName, userId, cachePolicy) {
     return this.getList(
-      this.sitePath(siteName, "users", `${userId}/subscriptions`)
+      this.sitePath(siteName, "users", `${userId}/subscriptions`),
+      void 0,
+      cachePolicy
     );
   }
   /** Pause a user's subscription (admin). */
@@ -4177,15 +4183,16 @@ function createPerspectAb(options) {
           `${VID_COOKIE}=${visitorId}; Path=/; Max-Age=${VID_COOKIE_MAX_AGE}; SameSite=Lax; Secure; HttpOnly`
         );
       }
+      const isBot = classifyBotFromCfRequest(request);
       const config = await getConfig(options.cache, apiKey, siteName, baseUrl);
-      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId), responseHeaders };
+      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId, isBot), responseHeaders };
     },
     async refreshConfig() {
       await fetchAndStoreConfig(options.cache, apiKey, siteName, baseUrl);
     }
   };
 }
-function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId) {
+function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId, isBot) {
   return {
     async getVariant(flagKey) {
       const flag = config.flags[flagKey];
@@ -4205,6 +4212,7 @@ function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId) {
         version: flag.currentVersion,
         variant: assigned,
         visitorId,
+        isBot,
         dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, "exposure"),
         ts: Math.floor(Date.now() / 1e3)
       });
@@ -4225,6 +4233,7 @@ function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId) {
           version: flag.currentVersion,
           variant: assigned,
           visitorId,
+          isBot,
           event,
           dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, event),
           ts: Math.floor(Date.now() / 1e3),
@@ -4263,6 +4272,13 @@ function emit(apiKey, baseUrl, ctx, body) {
   }).then(() => void 0).catch(() => void 0);
   if (ctx) ctx.waitUntil(task);
 }
+function classifyBotFromCfRequest(request) {
+  const cf = request.cf;
+  if (!cf?.botManagement) return false;
+  if (cf.botManagement.verifiedBot) return true;
+  if (typeof cf.botManagement.score === "number") return cf.botManagement.score < 30;
+  return false;
+}
 function readOrMintVid(request) {
   const cookie = request.headers.get("cookie") ?? "";
   const match = cookie.match(/(?:^|; )perspect_vid=([^;]+)/);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/ab/ab-client.ts

@@ -88,8 +88,9 @@ export function createPerspectAb(options: CreatePerspectAbOptions): PerspectAb {
           `${VID_COOKIE}=${visitorId}; Path=/; Max-Age=${VID_COOKIE_MAX_AGE}; SameSite=Lax; Secure; HttpOnly`,
         );
       }
+      const isBot = classifyBotFromCfRequest(request);
       const config = await getConfig(options.cache, apiKey, siteName, baseUrl);
-      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId), responseHeaders };
+      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId, isBot), responseHeaders };
     },
 
     async refreshConfig(): Promise<void> {
@@ -109,6 +110,7 @@ function buildAbClient(
   ctx: { waitUntil(p: Promise<unknown>): void } | undefined,
   config: AbConfigBlob,
   visitorId: string,
+  isBot: boolean,
 ): AbClient {
   return {
     async getVariant(flagKey: string): Promise<AbVariantResult> {
@@ -129,6 +131,7 @@ function buildAbClient(
         version: flag.currentVersion,
         variant: assigned,
         visitorId,
+        isBot,
         dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, 'exposure'),
         ts: Math.floor(Date.now() / 1000),
       });
@@ -150,6 +153,7 @@ function buildAbClient(
           version: flag.currentVersion,
           variant: assigned,
           visitorId,
+          isBot,
           event,
           dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, event),
           ts: Math.floor(Date.now() / 1000),
@@ -209,6 +213,7 @@ interface EventBody {
   version: number;
   variant: string;
   visitorId: string;
+  isBot: boolean;
   dedup: string;
   ts: number;
   event?: string;
@@ -231,6 +236,21 @@ function emit(
   if (ctx) ctx.waitUntil(task);
 }
 
+// ---------------------------------------------------------------------------
+// Bot classification from CF request metadata
+// ---------------------------------------------------------------------------
+
+// CF Workers attach botManagement to the request object at runtime. The SDK
+// uses the standard Request type, so we access it via an unsafe cast rather
+// than importing CF-specific types as a peer dependency.
+function classifyBotFromCfRequest(request: Request): boolean {
+  const cf = (request as unknown as { cf?: { botManagement?: { score?: number; verifiedBot?: boolean } } }).cf;
+  if (!cf?.botManagement) return false;
+  if (cf.botManagement.verifiedBot) return true;
+  if (typeof cf.botManagement.score === 'number') return cf.botManagement.score < 30;
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // Visitor ID
 // ---------------------------------------------------------------------------

package/src/v2/client/site-users-client.ts

@@ -9,6 +9,7 @@
  */
 
 import { BaseV2Client } from './base-v2-client';
+import type { CachePolicy } from '../../cache/types';
 import type {
   V2SiteUser,
   V2SiteUserUpdateParams,
@@ -91,9 +92,11 @@ export class SiteUsersV2Client extends BaseV2Client {
   }
 
   /** Fetch the profile KV map as a dedicated `site_user_profile` envelope. */
-  async getProfile(siteName: string): Promise<V2SiteUserProfile> {
+  async getProfile(siteName: string, cachePolicy?: CachePolicy): Promise<V2SiteUserProfile> {
     return this.getOne<V2SiteUserProfile>(
       this.sitePath(siteName, 'users', 'me/profile'),
+      undefined,
+      cachePolicy,
     );
   }
 

package/src/v2/client/subscriptions-client.ts

@@ -7,6 +7,7 @@
  */
 
 import { BaseV2Client } from './base-v2-client';
+import type { CachePolicy } from '../../cache/types';
 import type {
   V2SiteUserSubscription,
   V2SubscriptionPauseParams,
@@ -23,9 +24,12 @@ export class SubscriptionsV2Client extends BaseV2Client {
   /** List all subscriptions for the authenticated user. */
   async listMySubscriptions(
     siteName: string,
+    cachePolicy?: CachePolicy,
   ): Promise<V2List<V2SiteUserSubscription>> {
     return this.getList<V2SiteUserSubscription>(
       this.sitePath(siteName, 'users', 'me/subscriptions'),
+      undefined,
+      cachePolicy,
     );
   }
 
@@ -81,9 +85,12 @@ export class SubscriptionsV2Client extends BaseV2Client {
   async listUserSubscriptions(
     siteName: string,
     userId: string,
+    cachePolicy?: CachePolicy,
   ): Promise<V2List<V2SiteUserSubscription>> {
     return this.getList<V2SiteUserSubscription>(
       this.sitePath(siteName, 'users', `${userId}/subscriptions`),
+      undefined,
+      cachePolicy,
     );
   }