perspectapi-ts-sdk 6.1.1 → 6.2.0

package/dist/index.d.mts

@@ -4129,6 +4129,21 @@ declare class CloudflareKVCacheAdapter implements CacheAdapter {
     clear(): Promise<void>;
 }
 
+/**
+ * Simple in-memory cache adapter primarily suited for development and testing.
+ */
+
+declare class InMemoryCacheAdapter implements CacheAdapter {
+    private store;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteMany(keys: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
 /**
  * No-op cache adapter that disables caching while preserving the cache contract.
  */
@@ -4141,6 +4156,64 @@ declare class NoopCacheAdapter implements CacheAdapter {
     clear(): Promise<void>;
 }
 
+interface CreatePerspectAbOptions {
+    apiKey: string;
+    siteName: string;
+    baseUrl?: string;
+    /** Pluggable cache adapter — CloudflareKVCacheAdapter, InMemoryCacheAdapter, or NoopCacheAdapter. */
+    cache?: CacheAdapter;
+    /** ExecutionContext (CF Workers) or any object with waitUntil — enables background tasks. */
+    ctx?: {
+        waitUntil(p: Promise<unknown>): void;
+    };
+}
+interface AbForRequestResult {
+    ab: AbClient;
+    /** Merge into the outgoing response — may carry a freshly minted perspect_vid cookie. */
+    responseHeaders: Headers;
+}
+interface AbVariantResult {
+    variant: string | null;
+    enrolled: boolean;
+    config: Record<string, unknown> | null;
+}
+interface AbClient {
+    getVariant(flagKey: string): Promise<AbVariantResult>;
+    track(event: string, properties?: Record<string, unknown>): Promise<void>;
+}
+interface PerspectAb {
+    forRequest(request: Request): Promise<AbForRequestResult>;
+    refreshConfig(): Promise<void>;
+}
+declare function createPerspectAb(options: CreatePerspectAbOptions): PerspectAb;
+
+/**
+ * Deterministic bucketing for A/B assignments.
+ *
+ * Both the site SDK (local assignment) and the platform event endpoint
+ * (server-side validation) compute the same hash → variant mapping.
+ * Any change here must ship to both simultaneously, or assignments and
+ * validation will diverge.
+ */
+/**
+ * FNV-1a 32-bit over UTF-8 bytes, reduced mod 10000.
+ * Pure function, no crypto — determinism and portability beat pre-image
+ * resistance here. The attack surface on the mapping is the same for
+ * both sides; what matters is that site and platform agree bit-for-bit.
+ */
+declare function bucketFor(visitorId: string, flagKey: string, version: number): number;
+/**
+ * Resolve a bucket to a variant using cumulative weightBp ranges.
+ * Variants are consumed in the order given — callers must sort variants
+ * consistently on both sides (we sort by key).
+ *
+ * Returns null iff bucket >= trafficAllocationBp (visitor not enrolled).
+ */
+declare function variantForBucket(bucket: number, variants: {
+    key: string;
+    weightBp: number;
+}[], trafficAllocationBp: number): string | null;
+
 /**
  * Cloudflare Image Resizing Integration
  * Transforms images on-the-fly using Cloudflare's Image Resizing service
@@ -4383,6 +4456,17 @@ interface LoadContentBySlugOptions extends LoaderOptions {
  * Load a single content item (post or page) by slug.
  */
 declare function loadContentBySlug(options: LoadContentBySlugOptions): Promise<BlogPost | null>;
+interface LoadBlockBySlugOptions extends LoaderOptions {
+    slug: string;
+}
+/**
+ * Load published blocks for a site.
+ */
+declare function loadBlocks(options: LoadContentOptions): Promise<BlogPost[]>;
+/**
+ * Load a single block by slug.
+ */
+declare function loadBlockBySlug(options: LoadBlockBySlugOptions): Promise<BlogPost | null>;
 /**
  * Load all published content (pages + posts).
  */
@@ -4434,4 +4518,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type AddCollectionItemRequest, type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, BaseClient, type BlogPost, type BundleCollection, type BundleCollectionItem, type BundleCollectionItemWithProduct, BundlesClient, type CacheConfig, CacheManager, type CancelSubscriptionRequest, type CancelSubscriptionResponse, CategoriesClient, type Category, type CategorySummary, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, CloudflareKVCacheAdapter, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, type ContentCategoryResponse, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateBundleCollectionRequest, type CreateBundleGroupRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateProductSkuRequest, type CreateSiteRequest, type CreateWebhookRequest, type CreditBalance, type CreditBalanceWithTransactions, type CreditTransaction, DEFAULT_IMAGE_SIZES, type GrantCreditRequest, HttpClient, type HttpMethod, type ImageTransformOptions, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, type NewsletterCampaignDetail, type NewsletterCampaignListResponse, type NewsletterCampaignSummary, type NewsletterCampaignTestSendRequest, type NewsletterCampaignTestSendResponse, NewsletterClient, type NewsletterConfirmResponse, type NewsletterExportCreateRequest, type NewsletterExportCreateResponse, type NewsletterList, type NewsletterManagementCampaign, type NewsletterManagementCampaignListResponse, NewsletterManagementClient, type NewsletterManagementList, type NewsletterManagementListMembership, type NewsletterManagementPagination, type NewsletterManagementSeries, type NewsletterManagementStatsResponse, type NewsletterManagementSubscription, type NewsletterManagementSubscriptionsListResponse, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterSubscriptionImportRowRequest, type NewsletterSubscriptionMembershipUpdateRequest, type NewsletterSubscriptionSyncRequest, type NewsletterSubscriptionSyncResponse, type NewsletterSubscriptionsBulkAction, type NewsletterSubscriptionsBulkOutcome, type NewsletterSubscriptionsBulkUpdateRequest, type NewsletterSubscriptionsBulkUpdateResponse, type NewsletterSubscriptionsImportRequest, type NewsletterSubscriptionsImportResponse, type NewsletterSubscriptionsImportRowResult, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, PerspectApiV2Client, PerspectV2Error, type Product, type ProductBundleGroup, type ProductQueryParams, type ProductSku, type ProductSkuMediaItem, type ProductSkuOption, ProductsClient, type RequestOptions, type RequestOtpRequest, type ResponsiveImageSizes, type SetProfileValueRequest, type Site, type SiteUser, type SiteUserOrder, type SiteUserProfile, type SiteUserSubscription, SiteUsersClient, SitesClient, type SubscriptionCancellationMode, type UpdateApiKeyRequest, type UpdateContentRequest, type UpdateSiteUserRequest, type User, V1_DEPRECATION_NOTICE, V1_SUNSET_DATE, type V2ApiKey, type V2CancelSubscriptionResult, type V2Category, type V2CategoryCreateParams, type V2CategoryUpdateParams, type V2Collection, type V2CollectionCreateParams, type V2CollectionItem, type V2CollectionUpdateParams, type V2ContactSubmission, type V2Content, type V2ContentCreateParams, type V2ContentListParams, type V2ContentUpdateParams, type V2CreditBalance, type V2CreditTransaction, type V2Deleted, type V2Error, type V2ErrorType, type V2GrantCreditParams, type V2GrantCreditResult, type V2List, type V2Media, type V2NewsletterCampaign, type V2NewsletterImportRequest, type V2NewsletterImportResult, type V2NewsletterList, type V2NewsletterListCreateParams, type V2NewsletterListUpdateParams, type V2NewsletterSubscription, type V2NewsletterSubscriptionListMembershipUpdate, type V2NewsletterSyncInput, type V2NewsletterSyncResult, type V2NewsletterTrackingResponse, type V2Object, type V2Order, type V2OrderAddress, type V2OrderCreateParams, type V2OrderCreateResult, type V2OrderFulfillmentUpdate, type V2OrderLineItem, type V2OrderLineItemPriceData, type V2OrderListParams, type V2OrderTaxRequest, type V2Organization, type V2PaginationParams, type V2Product, type V2ProductCreateParams, type V2ProductListParams, type V2ProductUpdateParams, type V2Site, type V2SiteUser, type V2SiteUserListParams, type V2SiteUserMeUpdateParams, type V2SiteUserProfile, type V2SiteUserSubscription, type V2SiteUserUpdateParams, type V2SiteUserWithProfile, type V2SubscriptionCancelParams, type V2SubscriptionChangePlanParams, type V2SubscriptionPauseParams, type V2Webhook, type V2WebhookCreateParams, type V2WebhookUpdateParams, type VerifyOtpRequest, type VerifyOtpResponse, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, createPerspectApiV2Client, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type AbClient, type AbForRequestResult, type AbVariantResult, type AddCollectionItemRequest, type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, BaseClient, type BlogPost, type BundleCollection, type BundleCollectionItem, type BundleCollectionItemWithProduct, BundlesClient, type CacheAdapter, type CacheConfig, CacheManager, type CancelSubscriptionRequest, type CancelSubscriptionResponse, CategoriesClient, type Category, type CategorySummary, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, CloudflareKVCacheAdapter, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, type ContentCategoryResponse, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateBundleCollectionRequest, type CreateBundleGroupRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreatePerspectAbOptions, type CreateProductRequest, type CreateProductSkuRequest, type CreateSiteRequest, type CreateWebhookRequest, type CreditBalance, type CreditBalanceWithTransactions, type CreditTransaction, DEFAULT_IMAGE_SIZES, type GrantCreditRequest, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadBlockBySlugOptions, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, type NewsletterCampaignDetail, type NewsletterCampaignListResponse, type NewsletterCampaignSummary, type NewsletterCampaignTestSendRequest, type NewsletterCampaignTestSendResponse, NewsletterClient, type NewsletterConfirmResponse, type NewsletterExportCreateRequest, type NewsletterExportCreateResponse, type NewsletterList, type NewsletterManagementCampaign, type NewsletterManagementCampaignListResponse, NewsletterManagementClient, type NewsletterManagementList, type NewsletterManagementListMembership, type NewsletterManagementPagination, type NewsletterManagementSeries, type NewsletterManagementStatsResponse, type NewsletterManagementSubscription, type NewsletterManagementSubscriptionsListResponse, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterSubscriptionImportRowRequest, type NewsletterSubscriptionMembershipUpdateRequest, type NewsletterSubscriptionSyncRequest, type NewsletterSubscriptionSyncResponse, type NewsletterSubscriptionsBulkAction, type NewsletterSubscriptionsBulkOutcome, type NewsletterSubscriptionsBulkUpdateRequest, type NewsletterSubscriptionsBulkUpdateResponse, type NewsletterSubscriptionsImportRequest, type NewsletterSubscriptionsImportResponse, type NewsletterSubscriptionsImportRowResult, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, type PerspectAb, PerspectApiClient, type PerspectApiConfig, PerspectApiV2Client, PerspectV2Error, type Product, type ProductBundleGroup, type ProductQueryParams, type ProductSku, type ProductSkuMediaItem, type ProductSkuOption, ProductsClient, type RequestOptions, type RequestOtpRequest, type ResponsiveImageSizes, type SetProfileValueRequest, type Site, type SiteUser, type SiteUserOrder, type SiteUserProfile, type SiteUserSubscription, SiteUsersClient, SitesClient, type SubscriptionCancellationMode, type UpdateApiKeyRequest, type UpdateContentRequest, type UpdateSiteUserRequest, type User, V1_DEPRECATION_NOTICE, V1_SUNSET_DATE, type V2ApiKey, type V2CancelSubscriptionResult, type V2Category, type V2CategoryCreateParams, type V2CategoryUpdateParams, type V2Collection, type V2CollectionCreateParams, type V2CollectionItem, type V2CollectionUpdateParams, type V2ContactSubmission, type V2Content, type V2ContentCreateParams, type V2ContentListParams, type V2ContentUpdateParams, type V2CreditBalance, type V2CreditTransaction, type V2Deleted, type V2Error, type V2ErrorType, type V2GrantCreditParams, type V2GrantCreditResult, type V2List, type V2Media, type V2NewsletterCampaign, type V2NewsletterImportRequest, type V2NewsletterImportResult, type V2NewsletterList, type V2NewsletterListCreateParams, type V2NewsletterListUpdateParams, type V2NewsletterSubscription, type V2NewsletterSubscriptionListMembershipUpdate, type V2NewsletterSyncInput, type V2NewsletterSyncResult, type V2NewsletterTrackingResponse, type V2Object, type V2Order, type V2OrderAddress, type V2OrderCreateParams, type V2OrderCreateResult, type V2OrderFulfillmentUpdate, type V2OrderLineItem, type V2OrderLineItemPriceData, type V2OrderListParams, type V2OrderTaxRequest, type V2Organization, type V2PaginationParams, type V2Product, type V2ProductCreateParams, type V2ProductListParams, type V2ProductUpdateParams, type V2Site, type V2SiteUser, type V2SiteUserListParams, type V2SiteUserMeUpdateParams, type V2SiteUserProfile, type V2SiteUserSubscription, type V2SiteUserUpdateParams, type V2SiteUserWithProfile, type V2SubscriptionCancelParams, type V2SubscriptionChangePlanParams, type V2SubscriptionPauseParams, type V2Webhook, type V2WebhookCreateParams, type V2WebhookUpdateParams, type VerifyOtpRequest, type VerifyOtpResponse, type Webhook, WebhooksClient, bucketFor, buildImageUrl, createApiError, createCheckoutSession, createPerspectAb, createPerspectApiClient, createPerspectApiV2Client, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadBlockBySlug, loadBlocks, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct, variantForBucket };

package/dist/index.d.ts

@@ -4129,6 +4129,21 @@ declare class CloudflareKVCacheAdapter implements CacheAdapter {
     clear(): Promise<void>;
 }
 
+/**
+ * Simple in-memory cache adapter primarily suited for development and testing.
+ */
+
+declare class InMemoryCacheAdapter implements CacheAdapter {
+    private store;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteMany(keys: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
 /**
  * No-op cache adapter that disables caching while preserving the cache contract.
  */
@@ -4141,6 +4156,64 @@ declare class NoopCacheAdapter implements CacheAdapter {
     clear(): Promise<void>;
 }
 
+interface CreatePerspectAbOptions {
+    apiKey: string;
+    siteName: string;
+    baseUrl?: string;
+    /** Pluggable cache adapter — CloudflareKVCacheAdapter, InMemoryCacheAdapter, or NoopCacheAdapter. */
+    cache?: CacheAdapter;
+    /** ExecutionContext (CF Workers) or any object with waitUntil — enables background tasks. */
+    ctx?: {
+        waitUntil(p: Promise<unknown>): void;
+    };
+}
+interface AbForRequestResult {
+    ab: AbClient;
+    /** Merge into the outgoing response — may carry a freshly minted perspect_vid cookie. */
+    responseHeaders: Headers;
+}
+interface AbVariantResult {
+    variant: string | null;
+    enrolled: boolean;
+    config: Record<string, unknown> | null;
+}
+interface AbClient {
+    getVariant(flagKey: string): Promise<AbVariantResult>;
+    track(event: string, properties?: Record<string, unknown>): Promise<void>;
+}
+interface PerspectAb {
+    forRequest(request: Request): Promise<AbForRequestResult>;
+    refreshConfig(): Promise<void>;
+}
+declare function createPerspectAb(options: CreatePerspectAbOptions): PerspectAb;
+
+/**
+ * Deterministic bucketing for A/B assignments.
+ *
+ * Both the site SDK (local assignment) and the platform event endpoint
+ * (server-side validation) compute the same hash → variant mapping.
+ * Any change here must ship to both simultaneously, or assignments and
+ * validation will diverge.
+ */
+/**
+ * FNV-1a 32-bit over UTF-8 bytes, reduced mod 10000.
+ * Pure function, no crypto — determinism and portability beat pre-image
+ * resistance here. The attack surface on the mapping is the same for
+ * both sides; what matters is that site and platform agree bit-for-bit.
+ */
+declare function bucketFor(visitorId: string, flagKey: string, version: number): number;
+/**
+ * Resolve a bucket to a variant using cumulative weightBp ranges.
+ * Variants are consumed in the order given — callers must sort variants
+ * consistently on both sides (we sort by key).
+ *
+ * Returns null iff bucket >= trafficAllocationBp (visitor not enrolled).
+ */
+declare function variantForBucket(bucket: number, variants: {
+    key: string;
+    weightBp: number;
+}[], trafficAllocationBp: number): string | null;
+
 /**
  * Cloudflare Image Resizing Integration
  * Transforms images on-the-fly using Cloudflare's Image Resizing service
@@ -4383,6 +4456,17 @@ interface LoadContentBySlugOptions extends LoaderOptions {
  * Load a single content item (post or page) by slug.
  */
 declare function loadContentBySlug(options: LoadContentBySlugOptions): Promise<BlogPost | null>;
+interface LoadBlockBySlugOptions extends LoaderOptions {
+    slug: string;
+}
+/**
+ * Load published blocks for a site.
+ */
+declare function loadBlocks(options: LoadContentOptions): Promise<BlogPost[]>;
+/**
+ * Load a single block by slug.
+ */
+declare function loadBlockBySlug(options: LoadBlockBySlugOptions): Promise<BlogPost | null>;
 /**
  * Load all published content (pages + posts).
  */
@@ -4434,4 +4518,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type AddCollectionItemRequest, type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, BaseClient, type BlogPost, type BundleCollection, type BundleCollectionItem, type BundleCollectionItemWithProduct, BundlesClient, type CacheConfig, CacheManager, type CancelSubscriptionRequest, type CancelSubscriptionResponse, CategoriesClient, type Category, type CategorySummary, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, CloudflareKVCacheAdapter, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, type ContentCategoryResponse, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateBundleCollectionRequest, type CreateBundleGroupRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateProductSkuRequest, type CreateSiteRequest, type CreateWebhookRequest, type CreditBalance, type CreditBalanceWithTransactions, type CreditTransaction, DEFAULT_IMAGE_SIZES, type GrantCreditRequest, HttpClient, type HttpMethod, type ImageTransformOptions, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, type NewsletterCampaignDetail, type NewsletterCampaignListResponse, type NewsletterCampaignSummary, type NewsletterCampaignTestSendRequest, type NewsletterCampaignTestSendResponse, NewsletterClient, type NewsletterConfirmResponse, type NewsletterExportCreateRequest, type NewsletterExportCreateResponse, type NewsletterList, type NewsletterManagementCampaign, type NewsletterManagementCampaignListResponse, NewsletterManagementClient, type NewsletterManagementList, type NewsletterManagementListMembership, type NewsletterManagementPagination, type NewsletterManagementSeries, type NewsletterManagementStatsResponse, type NewsletterManagementSubscription, type NewsletterManagementSubscriptionsListResponse, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterSubscriptionImportRowRequest, type NewsletterSubscriptionMembershipUpdateRequest, type NewsletterSubscriptionSyncRequest, type NewsletterSubscriptionSyncResponse, type NewsletterSubscriptionsBulkAction, type NewsletterSubscriptionsBulkOutcome, type NewsletterSubscriptionsBulkUpdateRequest, type NewsletterSubscriptionsBulkUpdateResponse, type NewsletterSubscriptionsImportRequest, type NewsletterSubscriptionsImportResponse, type NewsletterSubscriptionsImportRowResult, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, PerspectApiV2Client, PerspectV2Error, type Product, type ProductBundleGroup, type ProductQueryParams, type ProductSku, type ProductSkuMediaItem, type ProductSkuOption, ProductsClient, type RequestOptions, type RequestOtpRequest, type ResponsiveImageSizes, type SetProfileValueRequest, type Site, type SiteUser, type SiteUserOrder, type SiteUserProfile, type SiteUserSubscription, SiteUsersClient, SitesClient, type SubscriptionCancellationMode, type UpdateApiKeyRequest, type UpdateContentRequest, type UpdateSiteUserRequest, type User, V1_DEPRECATION_NOTICE, V1_SUNSET_DATE, type V2ApiKey, type V2CancelSubscriptionResult, type V2Category, type V2CategoryCreateParams, type V2CategoryUpdateParams, type V2Collection, type V2CollectionCreateParams, type V2CollectionItem, type V2CollectionUpdateParams, type V2ContactSubmission, type V2Content, type V2ContentCreateParams, type V2ContentListParams, type V2ContentUpdateParams, type V2CreditBalance, type V2CreditTransaction, type V2Deleted, type V2Error, type V2ErrorType, type V2GrantCreditParams, type V2GrantCreditResult, type V2List, type V2Media, type V2NewsletterCampaign, type V2NewsletterImportRequest, type V2NewsletterImportResult, type V2NewsletterList, type V2NewsletterListCreateParams, type V2NewsletterListUpdateParams, type V2NewsletterSubscription, type V2NewsletterSubscriptionListMembershipUpdate, type V2NewsletterSyncInput, type V2NewsletterSyncResult, type V2NewsletterTrackingResponse, type V2Object, type V2Order, type V2OrderAddress, type V2OrderCreateParams, type V2OrderCreateResult, type V2OrderFulfillmentUpdate, type V2OrderLineItem, type V2OrderLineItemPriceData, type V2OrderListParams, type V2OrderTaxRequest, type V2Organization, type V2PaginationParams, type V2Product, type V2ProductCreateParams, type V2ProductListParams, type V2ProductUpdateParams, type V2Site, type V2SiteUser, type V2SiteUserListParams, type V2SiteUserMeUpdateParams, type V2SiteUserProfile, type V2SiteUserSubscription, type V2SiteUserUpdateParams, type V2SiteUserWithProfile, type V2SubscriptionCancelParams, type V2SubscriptionChangePlanParams, type V2SubscriptionPauseParams, type V2Webhook, type V2WebhookCreateParams, type V2WebhookUpdateParams, type VerifyOtpRequest, type VerifyOtpResponse, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, createPerspectApiV2Client, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type AbClient, type AbForRequestResult, type AbVariantResult, type AddCollectionItemRequest, type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, BaseClient, type BlogPost, type BundleCollection, type BundleCollectionItem, type BundleCollectionItemWithProduct, BundlesClient, type CacheAdapter, type CacheConfig, CacheManager, type CancelSubscriptionRequest, type CancelSubscriptionResponse, CategoriesClient, type Category, type CategorySummary, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, CloudflareKVCacheAdapter, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, type ContentCategoryResponse, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateBundleCollectionRequest, type CreateBundleGroupRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreatePerspectAbOptions, type CreateProductRequest, type CreateProductSkuRequest, type CreateSiteRequest, type CreateWebhookRequest, type CreditBalance, type CreditBalanceWithTransactions, type CreditTransaction, DEFAULT_IMAGE_SIZES, type GrantCreditRequest, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadBlockBySlugOptions, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, type NewsletterCampaignDetail, type NewsletterCampaignListResponse, type NewsletterCampaignSummary, type NewsletterCampaignTestSendRequest, type NewsletterCampaignTestSendResponse, NewsletterClient, type NewsletterConfirmResponse, type NewsletterExportCreateRequest, type NewsletterExportCreateResponse, type NewsletterList, type NewsletterManagementCampaign, type NewsletterManagementCampaignListResponse, NewsletterManagementClient, type NewsletterManagementList, type NewsletterManagementListMembership, type NewsletterManagementPagination, type NewsletterManagementSeries, type NewsletterManagementStatsResponse, type NewsletterManagementSubscription, type NewsletterManagementSubscriptionsListResponse, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterSubscriptionImportRowRequest, type NewsletterSubscriptionMembershipUpdateRequest, type NewsletterSubscriptionSyncRequest, type NewsletterSubscriptionSyncResponse, type NewsletterSubscriptionsBulkAction, type NewsletterSubscriptionsBulkOutcome, type NewsletterSubscriptionsBulkUpdateRequest, type NewsletterSubscriptionsBulkUpdateResponse, type NewsletterSubscriptionsImportRequest, type NewsletterSubscriptionsImportResponse, type NewsletterSubscriptionsImportRowResult, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, type PerspectAb, PerspectApiClient, type PerspectApiConfig, PerspectApiV2Client, PerspectV2Error, type Product, type ProductBundleGroup, type ProductQueryParams, type ProductSku, type ProductSkuMediaItem, type ProductSkuOption, ProductsClient, type RequestOptions, type RequestOtpRequest, type ResponsiveImageSizes, type SetProfileValueRequest, type Site, type SiteUser, type SiteUserOrder, type SiteUserProfile, type SiteUserSubscription, SiteUsersClient, SitesClient, type SubscriptionCancellationMode, type UpdateApiKeyRequest, type UpdateContentRequest, type UpdateSiteUserRequest, type User, V1_DEPRECATION_NOTICE, V1_SUNSET_DATE, type V2ApiKey, type V2CancelSubscriptionResult, type V2Category, type V2CategoryCreateParams, type V2CategoryUpdateParams, type V2Collection, type V2CollectionCreateParams, type V2CollectionItem, type V2CollectionUpdateParams, type V2ContactSubmission, type V2Content, type V2ContentCreateParams, type V2ContentListParams, type V2ContentUpdateParams, type V2CreditBalance, type V2CreditTransaction, type V2Deleted, type V2Error, type V2ErrorType, type V2GrantCreditParams, type V2GrantCreditResult, type V2List, type V2Media, type V2NewsletterCampaign, type V2NewsletterImportRequest, type V2NewsletterImportResult, type V2NewsletterList, type V2NewsletterListCreateParams, type V2NewsletterListUpdateParams, type V2NewsletterSubscription, type V2NewsletterSubscriptionListMembershipUpdate, type V2NewsletterSyncInput, type V2NewsletterSyncResult, type V2NewsletterTrackingResponse, type V2Object, type V2Order, type V2OrderAddress, type V2OrderCreateParams, type V2OrderCreateResult, type V2OrderFulfillmentUpdate, type V2OrderLineItem, type V2OrderLineItemPriceData, type V2OrderListParams, type V2OrderTaxRequest, type V2Organization, type V2PaginationParams, type V2Product, type V2ProductCreateParams, type V2ProductListParams, type V2ProductUpdateParams, type V2Site, type V2SiteUser, type V2SiteUserListParams, type V2SiteUserMeUpdateParams, type V2SiteUserProfile, type V2SiteUserSubscription, type V2SiteUserUpdateParams, type V2SiteUserWithProfile, type V2SubscriptionCancelParams, type V2SubscriptionChangePlanParams, type V2SubscriptionPauseParams, type V2Webhook, type V2WebhookCreateParams, type V2WebhookUpdateParams, type VerifyOtpRequest, type VerifyOtpResponse, type Webhook, WebhooksClient, bucketFor, buildImageUrl, createApiError, createCheckoutSession, createPerspectAb, createPerspectApiClient, createPerspectApiV2Client, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadBlockBySlug, loadBlocks, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct, variantForBucket };

package/dist/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   ContentClient: () => ContentClient,
   DEFAULT_IMAGE_SIZES: () => DEFAULT_IMAGE_SIZES,
   HttpClient: () => HttpClient,
+  InMemoryCacheAdapter: () => InMemoryCacheAdapter,
   NewsletterClient: () => NewsletterClient,
   NewsletterManagementClient: () => NewsletterManagementClient,
   NoopCacheAdapter: () => NoopCacheAdapter,
@@ -45,9 +46,11 @@ __export(index_exports, {
   V1_DEPRECATION_NOTICE: () => V1_DEPRECATION_NOTICE,
   V1_SUNSET_DATE: () => V1_SUNSET_DATE,
   WebhooksClient: () => WebhooksClient,
+  bucketFor: () => bucketFor,
   buildImageUrl: () => buildImageUrl,
   createApiError: () => createApiError,
   createCheckoutSession: () => createCheckoutSession,
+  createPerspectAb: () => createPerspectAb,
   createPerspectApiClient: () => createPerspectApiClient,
   createPerspectApiV2Client: () => createPerspectApiV2Client,
   default: () => perspect_api_client_default,
@@ -56,6 +59,8 @@ __export(index_exports, {
   generateSizesAttribute: () => generateSizesAttribute,
   generateSrcSet: () => generateSrcSet,
   loadAllContent: () => loadAllContent,
+  loadBlockBySlug: () => loadBlockBySlug,
+  loadBlocks: () => loadBlocks,
   loadContentBySlug: () => loadContentBySlug,
   loadPages: () => loadPages,
   loadPosts: () => loadPosts,
@@ -63,7 +68,8 @@ __export(index_exports, {
   loadProducts: () => loadProducts,
   transformContent: () => transformContent,
   transformMediaItem: () => transformMediaItem,
-  transformProduct: () => transformProduct
+  transformProduct: () => transformProduct,
+  variantForBucket: () => variantForBucket
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -4137,6 +4143,180 @@ var CloudflareKVCacheAdapter = class {
   }
 };
 
+// src/cache/in-memory-adapter.ts
+var InMemoryCacheAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (entry.expiresAt && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  async set(key, value, options) {
+    const expiresAt = options?.ttlSeconds && options.ttlSeconds > 0 ? Date.now() + options.ttlSeconds * 1e3 : void 0;
+    this.store.set(key, { value, expiresAt });
+  }
+  async delete(key) {
+    this.store.delete(key);
+  }
+  async deleteMany(keys) {
+    keys.forEach((key) => this.store.delete(key));
+  }
+  async clear() {
+    this.store.clear();
+  }
+};
+
+// src/ab/bucketing.ts
+var BUCKET_SPACE = 1e4;
+function bucketFor(visitorId, flagKey, version) {
+  const input = `${visitorId}|${flagKey}|${version}`;
+  const bytes = new TextEncoder().encode(input);
+  let hash = 2166136261;
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) % BUCKET_SPACE;
+}
+function variantForBucket(bucket, variants, trafficAllocationBp) {
+  if (bucket >= trafficAllocationBp) return null;
+  const sorted = [...variants].sort((a, b) => a.key < b.key ? -1 : 1);
+  const totalWeight = sorted.reduce((acc, v) => acc + v.weightBp, 0);
+  if (totalWeight <= 0) return null;
+  const scaled = Math.floor(bucket * totalWeight / trafficAllocationBp);
+  let cursor = 0;
+  for (const v of sorted) {
+    cursor += v.weightBp;
+    if (scaled < cursor) return v.key;
+  }
+  return sorted[sorted.length - 1].key;
+}
+
+// src/ab/ab-client.ts
+var CONFIG_TTL_SECONDS = 3600;
+var VID_COOKIE = "perspect_vid";
+var VID_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 * 2;
+var BASE_URL_DEFAULT = "https://api.perspect.com";
+function createPerspectAb(options) {
+  const { apiKey, siteName, ctx } = options;
+  const baseUrl = (options.baseUrl ?? BASE_URL_DEFAULT).replace(/\/$/, "");
+  return {
+    async forRequest(request) {
+      const { visitorId, mintedNew } = readOrMintVid(request);
+      const responseHeaders = new Headers();
+      if (mintedNew) {
+        responseHeaders.append(
+          "Set-Cookie",
+          `${VID_COOKIE}=${visitorId}; Path=/; Max-Age=${VID_COOKIE_MAX_AGE}; SameSite=Lax; Secure; HttpOnly`
+        );
+      }
+      const config = await getConfig(options.cache, apiKey, siteName, baseUrl);
+      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId), responseHeaders };
+    },
+    async refreshConfig() {
+      await fetchAndStoreConfig(options.cache, apiKey, siteName, baseUrl);
+    }
+  };
+}
+function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId) {
+  return {
+    async getVariant(flagKey) {
+      const flag = config.flags[flagKey];
+      if (!flag || flag.status !== "running") {
+        return { variant: flag?.defaultVariant ?? null, enrolled: false, config: null };
+      }
+      const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+      const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+      if (assigned === null) {
+        return { variant: flag.defaultVariant, enrolled: false, config: null };
+      }
+      const variantCfg = flag.variants.find((v) => v.key === assigned)?.config ?? null;
+      emit(apiKey, baseUrl, ctx, {
+        site: siteName,
+        kind: "exposure",
+        flag: flagKey,
+        version: flag.currentVersion,
+        variant: assigned,
+        visitorId,
+        dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, "exposure"),
+        ts: Math.floor(Date.now() / 1e3)
+      });
+      return { variant: assigned, enrolled: true, config: variantCfg };
+    },
+    async track(event, properties) {
+      for (const [flagKey, flag] of Object.entries(config.flags)) {
+        if (flag.status !== "running") continue;
+        const goals = flag.goalsByVersion[String(flag.currentVersion)] ?? [];
+        if (!goals.includes(event)) continue;
+        const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+        const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+        if (assigned === null) continue;
+        emit(apiKey, baseUrl, ctx, {
+          site: siteName,
+          kind: "conversion",
+          flag: flagKey,
+          version: flag.currentVersion,
+          variant: assigned,
+          visitorId,
+          event,
+          dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, event),
+          ts: Math.floor(Date.now() / 1e3),
+          properties
+        });
+      }
+    }
+  };
+}
+function configCacheKey(siteName) {
+  return `ab:config:${siteName}`;
+}
+async function getConfig(cache, apiKey, siteName, baseUrl) {
+  if (cache) {
+    const raw = await cache.get(configCacheKey(siteName));
+    if (raw) return JSON.parse(raw);
+  }
+  return fetchAndStoreConfig(cache, apiKey, siteName, baseUrl);
+}
+async function fetchAndStoreConfig(cache, apiKey, siteName, baseUrl) {
+  const res = await fetch(`${baseUrl}/_ab/config?site=${encodeURIComponent(siteName)}`, {
+    headers: { "x-api-key": apiKey }
+  });
+  if (!res.ok) return { schemaVersion: 1, flags: {} };
+  const config = await res.json();
+  if (cache) {
+    await cache.set(configCacheKey(siteName), JSON.stringify(config), { ttlSeconds: CONFIG_TTL_SECONDS });
+  }
+  return config;
+}
+function emit(apiKey, baseUrl, ctx, body) {
+  const task = fetch(`${baseUrl}/_ab/event`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-api-key": apiKey },
+    body: JSON.stringify(body)
+  }).then(() => void 0).catch(() => void 0);
+  if (ctx) ctx.waitUntil(task);
+}
+function readOrMintVid(request) {
+  const cookie = request.headers.get("cookie") ?? "";
+  const match = cookie.match(/(?:^|; )perspect_vid=([^;]+)/);
+  if (match) return { visitorId: decodeURIComponent(match[1]), mintedNew: false };
+  return { visitorId: crypto.randomUUID().replace(/-/g, ""), mintedNew: true };
+}
+async function dedupFor(visitorId, flagKey, version, variant, event) {
+  const input = `${visitorId}|${flagKey}|${version}|${variant}|${event}`;
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  const bytes = new Uint8Array(digest);
+  let hex = "";
+  for (let i = 0; i < 16; i++) hex += bytes[i].toString(16).padStart(2, "0");
+  return hex;
+}
+
 // src/utils/image-transform.ts
 var DEFAULT_IMAGE_SIZES = {
   thumbnail: {
@@ -4639,6 +4819,56 @@ async function loadContentBySlug(options) {
     return null;
   }
 }
+async function loadBlocks(options) {
+  const { client, siteName, logger = noopLogger, params } = options;
+  if (!client) {
+    log(logger, "warn", "[PerspectAPI] No client configured, cannot load blocks");
+    return [];
+  }
+  try {
+    log(logger, "info", `[PerspectAPI] Loading blocks for site "${siteName}"`);
+    const requestedLimit = options.limit !== void 0 ? options.limit : params?.limit;
+    const resolvedLimit = validateLimit(
+      requestedLimit ?? MAX_API_QUERY_LIMIT,
+      "blocks query"
+    );
+    const response = await client.content.getContent(
+      siteName,
+      {
+        ...params,
+        page_status: params?.page_status ?? "publish",
+        page_type: "block",
+        limit: resolvedLimit
+      }
+    );
+    if (!response.data) {
+      return [];
+    }
+    return response.data.map((content) => transformContent(content, logger));
+  } catch (error) {
+    log(logger, "error", "[PerspectAPI] Error loading blocks", error);
+    return [];
+  }
+}
+async function loadBlockBySlug(options) {
+  const { client, siteName, slug, logger = noopLogger } = options;
+  if (!client) {
+    log(logger, "warn", "[PerspectAPI] No client configured, cannot load block");
+    return null;
+  }
+  try {
+    log(logger, "info", `[PerspectAPI] Loading block slug "${slug}" for site "${siteName}"`);
+    const response = await client.content.getContentBySlug(siteName, slug);
+    if (!response.data) {
+      log(logger, "warn", `[PerspectAPI] Block not found for slug "${slug}"`);
+      return null;
+    }
+    return transformContent(response.data, logger);
+  } catch (error) {
+    log(logger, "error", `[PerspectAPI] Error loading block slug "${slug}"`, error);
+    return null;
+  }
+}
 async function loadAllContent(options) {
   const { logger = noopLogger } = options;
   const [pages, posts] = await Promise.all([
@@ -4758,6 +4988,7 @@ async function createCheckoutSession(options) {
   ContentClient,
   DEFAULT_IMAGE_SIZES,
   HttpClient,
+  InMemoryCacheAdapter,
   NewsletterClient,
   NewsletterManagementClient,
   NoopCacheAdapter,
@@ -4771,9 +5002,11 @@ async function createCheckoutSession(options) {
   V1_DEPRECATION_NOTICE,
   V1_SUNSET_DATE,
   WebhooksClient,
+  bucketFor,
   buildImageUrl,
   createApiError,
   createCheckoutSession,
+  createPerspectAb,
   createPerspectApiClient,
   createPerspectApiV2Client,
   generateResponsiveImageHtml,
@@ -4781,6 +5014,8 @@ async function createCheckoutSession(options) {
   generateSizesAttribute,
   generateSrcSet,
   loadAllContent,
+  loadBlockBySlug,
+  loadBlocks,
   loadContentBySlug,
   loadPages,
   loadPosts,
@@ -4788,5 +5023,6 @@ async function createCheckoutSession(options) {
   loadProducts,
   transformContent,
   transformMediaItem,
-  transformProduct
+  transformProduct,
+  variantForBucket
 });

package/dist/index.mjs

@@ -4068,6 +4068,180 @@ var CloudflareKVCacheAdapter = class {
   }
 };
 
+// src/cache/in-memory-adapter.ts
+var InMemoryCacheAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (entry.expiresAt && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  async set(key, value, options) {
+    const expiresAt = options?.ttlSeconds && options.ttlSeconds > 0 ? Date.now() + options.ttlSeconds * 1e3 : void 0;
+    this.store.set(key, { value, expiresAt });
+  }
+  async delete(key) {
+    this.store.delete(key);
+  }
+  async deleteMany(keys) {
+    keys.forEach((key) => this.store.delete(key));
+  }
+  async clear() {
+    this.store.clear();
+  }
+};
+
+// src/ab/bucketing.ts
+var BUCKET_SPACE = 1e4;
+function bucketFor(visitorId, flagKey, version) {
+  const input = `${visitorId}|${flagKey}|${version}`;
+  const bytes = new TextEncoder().encode(input);
+  let hash = 2166136261;
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) % BUCKET_SPACE;
+}
+function variantForBucket(bucket, variants, trafficAllocationBp) {
+  if (bucket >= trafficAllocationBp) return null;
+  const sorted = [...variants].sort((a, b) => a.key < b.key ? -1 : 1);
+  const totalWeight = sorted.reduce((acc, v) => acc + v.weightBp, 0);
+  if (totalWeight <= 0) return null;
+  const scaled = Math.floor(bucket * totalWeight / trafficAllocationBp);
+  let cursor = 0;
+  for (const v of sorted) {
+    cursor += v.weightBp;
+    if (scaled < cursor) return v.key;
+  }
+  return sorted[sorted.length - 1].key;
+}
+
+// src/ab/ab-client.ts
+var CONFIG_TTL_SECONDS = 3600;
+var VID_COOKIE = "perspect_vid";
+var VID_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 * 2;
+var BASE_URL_DEFAULT = "https://api.perspect.com";
+function createPerspectAb(options) {
+  const { apiKey, siteName, ctx } = options;
+  const baseUrl = (options.baseUrl ?? BASE_URL_DEFAULT).replace(/\/$/, "");
+  return {
+    async forRequest(request) {
+      const { visitorId, mintedNew } = readOrMintVid(request);
+      const responseHeaders = new Headers();
+      if (mintedNew) {
+        responseHeaders.append(
+          "Set-Cookie",
+          `${VID_COOKIE}=${visitorId}; Path=/; Max-Age=${VID_COOKIE_MAX_AGE}; SameSite=Lax; Secure; HttpOnly`
+        );
+      }
+      const config = await getConfig(options.cache, apiKey, siteName, baseUrl);
+      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId), responseHeaders };
+    },
+    async refreshConfig() {
+      await fetchAndStoreConfig(options.cache, apiKey, siteName, baseUrl);
+    }
+  };
+}
+function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId) {
+  return {
+    async getVariant(flagKey) {
+      const flag = config.flags[flagKey];
+      if (!flag || flag.status !== "running") {
+        return { variant: flag?.defaultVariant ?? null, enrolled: false, config: null };
+      }
+      const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+      const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+      if (assigned === null) {
+        return { variant: flag.defaultVariant, enrolled: false, config: null };
+      }
+      const variantCfg = flag.variants.find((v) => v.key === assigned)?.config ?? null;
+      emit(apiKey, baseUrl, ctx, {
+        site: siteName,
+        kind: "exposure",
+        flag: flagKey,
+        version: flag.currentVersion,
+        variant: assigned,
+        visitorId,
+        dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, "exposure"),
+        ts: Math.floor(Date.now() / 1e3)
+      });
+      return { variant: assigned, enrolled: true, config: variantCfg };
+    },
+    async track(event, properties) {
+      for (const [flagKey, flag] of Object.entries(config.flags)) {
+        if (flag.status !== "running") continue;
+        const goals = flag.goalsByVersion[String(flag.currentVersion)] ?? [];
+        if (!goals.includes(event)) continue;
+        const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+        const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+        if (assigned === null) continue;
+        emit(apiKey, baseUrl, ctx, {
+          site: siteName,
+          kind: "conversion",
+          flag: flagKey,
+          version: flag.currentVersion,
+          variant: assigned,
+          visitorId,
+          event,
+          dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, event),
+          ts: Math.floor(Date.now() / 1e3),
+          properties
+        });
+      }
+    }
+  };
+}
+function configCacheKey(siteName) {
+  return `ab:config:${siteName}`;
+}
+async function getConfig(cache, apiKey, siteName, baseUrl) {
+  if (cache) {
+    const raw = await cache.get(configCacheKey(siteName));
+    if (raw) return JSON.parse(raw);
+  }
+  return fetchAndStoreConfig(cache, apiKey, siteName, baseUrl);
+}
+async function fetchAndStoreConfig(cache, apiKey, siteName, baseUrl) {
+  const res = await fetch(`${baseUrl}/_ab/config?site=${encodeURIComponent(siteName)}`, {
+    headers: { "x-api-key": apiKey }
+  });
+  if (!res.ok) return { schemaVersion: 1, flags: {} };
+  const config = await res.json();
+  if (cache) {
+    await cache.set(configCacheKey(siteName), JSON.stringify(config), { ttlSeconds: CONFIG_TTL_SECONDS });
+  }
+  return config;
+}
+function emit(apiKey, baseUrl, ctx, body) {
+  const task = fetch(`${baseUrl}/_ab/event`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-api-key": apiKey },
+    body: JSON.stringify(body)
+  }).then(() => void 0).catch(() => void 0);
+  if (ctx) ctx.waitUntil(task);
+}
+function readOrMintVid(request) {
+  const cookie = request.headers.get("cookie") ?? "";
+  const match = cookie.match(/(?:^|; )perspect_vid=([^;]+)/);
+  if (match) return { visitorId: decodeURIComponent(match[1]), mintedNew: false };
+  return { visitorId: crypto.randomUUID().replace(/-/g, ""), mintedNew: true };
+}
+async function dedupFor(visitorId, flagKey, version, variant, event) {
+  const input = `${visitorId}|${flagKey}|${version}|${variant}|${event}`;
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  const bytes = new Uint8Array(digest);
+  let hex = "";
+  for (let i = 0; i < 16; i++) hex += bytes[i].toString(16).padStart(2, "0");
+  return hex;
+}
+
 // src/utils/image-transform.ts
 var DEFAULT_IMAGE_SIZES = {
   thumbnail: {
@@ -4570,6 +4744,56 @@ async function loadContentBySlug(options) {
     return null;
   }
 }
+async function loadBlocks(options) {
+  const { client, siteName, logger = noopLogger, params } = options;
+  if (!client) {
+    log(logger, "warn", "[PerspectAPI] No client configured, cannot load blocks");
+    return [];
+  }
+  try {
+    log(logger, "info", `[PerspectAPI] Loading blocks for site "${siteName}"`);
+    const requestedLimit = options.limit !== void 0 ? options.limit : params?.limit;
+    const resolvedLimit = validateLimit(
+      requestedLimit ?? MAX_API_QUERY_LIMIT,
+      "blocks query"
+    );
+    const response = await client.content.getContent(
+      siteName,
+      {
+        ...params,
+        page_status: params?.page_status ?? "publish",
+        page_type: "block",
+        limit: resolvedLimit
+      }
+    );
+    if (!response.data) {
+      return [];
+    }
+    return response.data.map((content) => transformContent(content, logger));
+  } catch (error) {
+    log(logger, "error", "[PerspectAPI] Error loading blocks", error);
+    return [];
+  }
+}
+async function loadBlockBySlug(options) {
+  const { client, siteName, slug, logger = noopLogger } = options;
+  if (!client) {
+    log(logger, "warn", "[PerspectAPI] No client configured, cannot load block");
+    return null;
+  }
+  try {
+    log(logger, "info", `[PerspectAPI] Loading block slug "${slug}" for site "${siteName}"`);
+    const response = await client.content.getContentBySlug(siteName, slug);
+    if (!response.data) {
+      log(logger, "warn", `[PerspectAPI] Block not found for slug "${slug}"`);
+      return null;
+    }
+    return transformContent(response.data, logger);
+  } catch (error) {
+    log(logger, "error", `[PerspectAPI] Error loading block slug "${slug}"`, error);
+    return null;
+  }
+}
 async function loadAllContent(options) {
   const { logger = noopLogger } = options;
   const [pages, posts] = await Promise.all([
@@ -4688,6 +4912,7 @@ export {
   ContentClient,
   DEFAULT_IMAGE_SIZES,
   HttpClient,
+  InMemoryCacheAdapter,
   NewsletterClient,
   NewsletterManagementClient,
   NoopCacheAdapter,
@@ -4701,9 +4926,11 @@ export {
   V1_DEPRECATION_NOTICE,
   V1_SUNSET_DATE,
   WebhooksClient,
+  bucketFor,
   buildImageUrl,
   createApiError,
   createCheckoutSession,
+  createPerspectAb,
   createPerspectApiClient,
   createPerspectApiV2Client,
   perspect_api_client_default as default,
@@ -4712,6 +4939,8 @@ export {
   generateSizesAttribute,
   generateSrcSet,
   loadAllContent,
+  loadBlockBySlug,
+  loadBlocks,
   loadContentBySlug,
   loadPages,
   loadPosts,
@@ -4719,5 +4948,6 @@ export {
   loadProducts,
   transformContent,
   transformMediaItem,
-  transformProduct
+  transformProduct,
+  variantForBucket
 };

package/package.json

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

package/src/ab/ab-client.ts

@@ -0,0 +1,262 @@
+import { bucketFor, variantForBucket } from './bucketing';
+import type { CacheAdapter } from '../cache/types';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface CreatePerspectAbOptions {
+  apiKey: string;
+  siteName: string;
+  baseUrl?: string;
+  /** Pluggable cache adapter — CloudflareKVCacheAdapter, InMemoryCacheAdapter, or NoopCacheAdapter. */
+  cache?: CacheAdapter;
+  /** ExecutionContext (CF Workers) or any object with waitUntil — enables background tasks. */
+  ctx?: { waitUntil(p: Promise<unknown>): void };
+}
+
+export interface AbForRequestResult {
+  ab: AbClient;
+  /** Merge into the outgoing response — may carry a freshly minted perspect_vid cookie. */
+  responseHeaders: Headers;
+}
+
+export interface AbVariantResult {
+  variant: string | null;
+  enrolled: boolean;
+  config: Record<string, unknown> | null;
+}
+
+export interface AbClient {
+  getVariant(flagKey: string): Promise<AbVariantResult>;
+  track(event: string, properties?: Record<string, unknown>): Promise<void>;
+}
+
+export interface PerspectAb {
+  forRequest(request: Request): Promise<AbForRequestResult>;
+  refreshConfig(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal config types
+// ---------------------------------------------------------------------------
+
+interface AbVariantCfg {
+  key: string;
+  weightBp: number;
+  config: Record<string, unknown> | null;
+}
+
+interface AbFlagCfg {
+  currentVersion: number;
+  status: 'draft' | 'running' | 'paused' | 'stopped';
+  variants: AbVariantCfg[];
+  trafficAllocationBp: number;
+  defaultVariant: string;
+  goalsByVersion: Record<string, string[]>;
+}
+
+interface AbConfigBlob {
+  schemaVersion: 1;
+  flags: Record<string, AbFlagCfg>;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CONFIG_TTL_SECONDS = 3_600;
+const VID_COOKIE = 'perspect_vid';
+const VID_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 * 2;
+const BASE_URL_DEFAULT = 'https://api.perspect.com';
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+export function createPerspectAb(options: CreatePerspectAbOptions): PerspectAb {
+  const { apiKey, siteName, ctx } = options;
+  const baseUrl = (options.baseUrl ?? BASE_URL_DEFAULT).replace(/\/$/, '');
+
+  return {
+    async forRequest(request: Request): Promise<AbForRequestResult> {
+      const { visitorId, mintedNew } = readOrMintVid(request);
+      const responseHeaders = new Headers();
+      if (mintedNew) {
+        responseHeaders.append(
+          'Set-Cookie',
+          `${VID_COOKIE}=${visitorId}; Path=/; Max-Age=${VID_COOKIE_MAX_AGE}; SameSite=Lax; Secure; HttpOnly`,
+        );
+      }
+      const config = await getConfig(options.cache, apiKey, siteName, baseUrl);
+      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId), responseHeaders };
+    },
+
+    async refreshConfig(): Promise<void> {
+      await fetchAndStoreConfig(options.cache, apiKey, siteName, baseUrl);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// AB client
+// ---------------------------------------------------------------------------
+
+function buildAbClient(
+  apiKey: string,
+  siteName: string,
+  baseUrl: string,
+  ctx: { waitUntil(p: Promise<unknown>): void } | undefined,
+  config: AbConfigBlob,
+  visitorId: string,
+): AbClient {
+  return {
+    async getVariant(flagKey: string): Promise<AbVariantResult> {
+      const flag = config.flags[flagKey];
+      if (!flag || flag.status !== 'running') {
+        return { variant: flag?.defaultVariant ?? null, enrolled: false, config: null };
+      }
+      const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+      const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+      if (assigned === null) {
+        return { variant: flag.defaultVariant, enrolled: false, config: null };
+      }
+      const variantCfg = flag.variants.find((v) => v.key === assigned)?.config ?? null;
+      emit(apiKey, baseUrl, ctx, {
+        site: siteName,
+        kind: 'exposure',
+        flag: flagKey,
+        version: flag.currentVersion,
+        variant: assigned,
+        visitorId,
+        dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, 'exposure'),
+        ts: Math.floor(Date.now() / 1000),
+      });
+      return { variant: assigned, enrolled: true, config: variantCfg };
+    },
+
+    async track(event: string, properties?: Record<string, unknown>): Promise<void> {
+      for (const [flagKey, flag] of Object.entries(config.flags)) {
+        if (flag.status !== 'running') continue;
+        const goals = flag.goalsByVersion[String(flag.currentVersion)] ?? [];
+        if (!goals.includes(event)) continue;
+        const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+        const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+        if (assigned === null) continue;
+        emit(apiKey, baseUrl, ctx, {
+          site: siteName,
+          kind: 'conversion',
+          flag: flagKey,
+          version: flag.currentVersion,
+          variant: assigned,
+          visitorId,
+          event,
+          dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, event),
+          ts: Math.floor(Date.now() / 1000),
+          properties,
+        });
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Config cache (SWR via CacheAdapter)
+// ---------------------------------------------------------------------------
+
+function configCacheKey(siteName: string): string {
+  return `ab:config:${siteName}`;
+}
+
+async function getConfig(
+  cache: CacheAdapter | undefined,
+  apiKey: string,
+  siteName: string,
+  baseUrl: string,
+): Promise<AbConfigBlob> {
+  if (cache) {
+    const raw = await cache.get(configCacheKey(siteName));
+    if (raw) return JSON.parse(raw) as AbConfigBlob;
+  }
+  return fetchAndStoreConfig(cache, apiKey, siteName, baseUrl);
+}
+
+async function fetchAndStoreConfig(
+  cache: CacheAdapter | undefined,
+  apiKey: string,
+  siteName: string,
+  baseUrl: string,
+): Promise<AbConfigBlob> {
+  const res = await fetch(`${baseUrl}/_ab/config?site=${encodeURIComponent(siteName)}`, {
+    headers: { 'x-api-key': apiKey },
+  });
+  if (!res.ok) return { schemaVersion: 1, flags: {} };
+  const config = (await res.json()) as AbConfigBlob;
+  if (cache) {
+    await cache.set(configCacheKey(siteName), JSON.stringify(config), { ttlSeconds: CONFIG_TTL_SECONDS });
+  }
+  return config;
+}
+
+// ---------------------------------------------------------------------------
+// Event emission
+// ---------------------------------------------------------------------------
+
+interface EventBody {
+  site: string;
+  kind: 'exposure' | 'conversion' | 'handoff';
+  flag: string;
+  version: number;
+  variant: string;
+  visitorId: string;
+  dedup: string;
+  ts: number;
+  event?: string;
+  properties?: Record<string, unknown>;
+}
+
+function emit(
+  apiKey: string,
+  baseUrl: string,
+  ctx: { waitUntil(p: Promise<unknown>): void } | undefined,
+  body: EventBody,
+): void {
+  const task = fetch(`${baseUrl}/_ab/event`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': apiKey },
+    body: JSON.stringify(body),
+  })
+    .then(() => undefined)
+    .catch(() => undefined);
+  if (ctx) ctx.waitUntil(task);
+}
+
+// ---------------------------------------------------------------------------
+// Visitor ID
+// ---------------------------------------------------------------------------
+
+function readOrMintVid(request: Request): { visitorId: string; mintedNew: boolean } {
+  const cookie = request.headers.get('cookie') ?? '';
+  const match = cookie.match(/(?:^|; )perspect_vid=([^;]+)/);
+  if (match) return { visitorId: decodeURIComponent(match[1]), mintedNew: false };
+  return { visitorId: crypto.randomUUID().replace(/-/g, ''), mintedNew: true };
+}
+
+// ---------------------------------------------------------------------------
+// Dedup hash
+// ---------------------------------------------------------------------------
+
+async function dedupFor(
+  visitorId: string,
+  flagKey: string,
+  version: number,
+  variant: string,
+  event: string,
+): Promise<string> {
+  const input = `${visitorId}|${flagKey}|${version}|${variant}|${event}`;
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
+  const bytes = new Uint8Array(digest);
+  let hex = '';
+  for (let i = 0; i < 16; i++) hex += bytes[i].toString(16).padStart(2, '0');
+  return hex;
+}

package/src/ab/bucketing.ts

@@ -0,0 +1,56 @@
+/**
+ * Deterministic bucketing for A/B assignments.
+ *
+ * Both the site SDK (local assignment) and the platform event endpoint
+ * (server-side validation) compute the same hash → variant mapping.
+ * Any change here must ship to both simultaneously, or assignments and
+ * validation will diverge.
+ */
+
+const BUCKET_SPACE = 10000;
+
+/**
+ * FNV-1a 32-bit over UTF-8 bytes, reduced mod 10000.
+ * Pure function, no crypto — determinism and portability beat pre-image
+ * resistance here. The attack surface on the mapping is the same for
+ * both sides; what matters is that site and platform agree bit-for-bit.
+ */
+export function bucketFor(
+  visitorId: string,
+  flagKey: string,
+  version: number,
+): number {
+  const input = `${visitorId}|${flagKey}|${version}`;
+  const bytes = new TextEncoder().encode(input);
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0) % BUCKET_SPACE;
+}
+
+/**
+ * Resolve a bucket to a variant using cumulative weightBp ranges.
+ * Variants are consumed in the order given — callers must sort variants
+ * consistently on both sides (we sort by key).
+ *
+ * Returns null iff bucket >= trafficAllocationBp (visitor not enrolled).
+ */
+export function variantForBucket(
+  bucket: number,
+  variants: { key: string; weightBp: number }[],
+  trafficAllocationBp: number,
+): string | null {
+  if (bucket >= trafficAllocationBp) return null;
+  const sorted = [...variants].sort((a, b) => (a.key < b.key ? -1 : 1));
+  const totalWeight = sorted.reduce((acc, v) => acc + v.weightBp, 0);
+  if (totalWeight <= 0) return null;
+  const scaled = Math.floor((bucket * totalWeight) / trafficAllocationBp);
+  let cursor = 0;
+  for (const v of sorted) {
+    cursor += v.weightBp;
+    if (scaled < cursor) return v.key;
+  }
+  return sorted[sorted.length - 1].key;
+}

package/src/index.ts

@@ -62,8 +62,20 @@ export { HttpClient, createApiError } from './utils/http-client';
 // Cache utilities
 export { CacheManager } from './cache/cache-manager';
 export { CloudflareKVCacheAdapter } from './cache/cloudflare-kv-adapter';
-// InMemoryCacheAdapter removed — useless in Cloudflare Workers (per-request memory, no persistence)
+export { InMemoryCacheAdapter } from './cache/in-memory-adapter';
 export { NoopCacheAdapter } from './cache/noop-adapter';
+export type { CacheAdapter, CacheConfig } from './cache/types';
+
+// A/B testing
+export { createPerspectAb } from './ab/ab-client';
+export { bucketFor, variantForBucket } from './ab/bucketing';
+export type {
+  CreatePerspectAbOptions,
+  PerspectAb,
+  AbClient,
+  AbVariantResult,
+  AbForRequestResult,
+} from './ab/ab-client';
 
 // Image transformation utilities
 export {
@@ -87,6 +99,8 @@ export {
   loadProductBySlug,
   loadPosts,
   loadPages,
+  loadBlocks,
+  loadBlockBySlug,
   loadContentBySlug,
   loadAllContent,
   createCheckoutSession,
@@ -100,6 +114,7 @@ export type {
   LoadProductBySlugOptions,
   LoadContentOptions,
   LoadContentBySlugOptions,
+  LoadBlockBySlugOptions,
   CheckoutSessionOptions,
   LoaderLogger
 } from './loaders';

package/src/loaders.ts

@@ -615,6 +615,83 @@ export async function loadContentBySlug(
   }
 }
 
+export interface LoadBlockBySlugOptions extends LoaderOptions {
+  slug: string;
+}
+
+/**
+ * Load published blocks for a site.
+ */
+export async function loadBlocks(
+  options: LoadContentOptions
+): Promise<BlogPost[]> {
+  const { client, siteName, logger = noopLogger, params } = options;
+
+  if (!client) {
+    log(logger, 'warn', '[PerspectAPI] No client configured, cannot load blocks');
+    return [];
+  }
+
+  try {
+    log(logger, 'info', `[PerspectAPI] Loading blocks for site "${siteName}"`);
+    const requestedLimit =
+      options.limit !== undefined ? options.limit : params?.limit;
+    const resolvedLimit = validateLimit(
+      requestedLimit ?? MAX_API_QUERY_LIMIT,
+      'blocks query',
+    );
+
+    const response: PaginatedResponse<Content> = await client.content.getContent(
+      siteName,
+      {
+        ...params,
+        page_status: (params?.page_status ?? 'publish') as ContentStatus,
+        page_type: 'block' as ContentType,
+        limit: resolvedLimit
+      }
+    );
+
+    if (!response.data) {
+      return [];
+    }
+
+    return response.data.map(content => transformContent(content, logger));
+  } catch (error) {
+    log(logger, 'error', '[PerspectAPI] Error loading blocks', error);
+    return [];
+  }
+}
+
+/**
+ * Load a single block by slug.
+ */
+export async function loadBlockBySlug(
+  options: LoadBlockBySlugOptions
+): Promise<BlogPost | null> {
+  const { client, siteName, slug, logger = noopLogger } = options;
+
+  if (!client) {
+    log(logger, 'warn', '[PerspectAPI] No client configured, cannot load block');
+    return null;
+  }
+
+  try {
+    log(logger, 'info', `[PerspectAPI] Loading block slug "${slug}" for site "${siteName}"`);
+    const response: ApiResponse<Content> =
+      await client.content.getContentBySlug(siteName, slug);
+
+    if (!response.data) {
+      log(logger, 'warn', `[PerspectAPI] Block not found for slug "${slug}"`);
+      return null;
+    }
+
+    return transformContent(response.data, logger);
+  } catch (error) {
+    log(logger, 'error', `[PerspectAPI] Error loading block slug "${slug}"`, error);
+    return null;
+  }
+}
+
 /**
  * Load all published content (pages + posts).
  */