perspectapi-ts-sdk 6.1.2 → 6.3.0

package/dist/index.d.mts

@@ -1079,6 +1079,12 @@ interface ApiError {
     status?: number;
     details?: any;
 }
+declare class PerspectApiError extends Error implements ApiError {
+    code?: string;
+    status?: number;
+    details?: any;
+    constructor({ message, code, status, details }: ApiError);
+}
 interface PerspectApiConfig {
     baseUrl: string;
     apiKey?: string;
@@ -4129,6 +4135,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 +4162,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
@@ -4445,4 +4524,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 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, 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, loadBlockBySlug, loadBlocks, 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, PerspectApiError, 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

@@ -1079,6 +1079,12 @@ interface ApiError {
     status?: number;
     details?: any;
 }
+declare class PerspectApiError extends Error implements ApiError {
+    code?: string;
+    status?: number;
+    details?: any;
+    constructor({ message, code, status, details }: ApiError);
+}
 interface PerspectApiConfig {
     baseUrl: string;
     apiKey?: string;
@@ -4129,6 +4135,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 +4162,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
@@ -4445,4 +4524,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 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, 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, loadBlockBySlug, loadBlocks, 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, PerspectApiError, 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,11 +32,13 @@ __export(index_exports, {
   ContentClient: () => ContentClient,
   DEFAULT_IMAGE_SIZES: () => DEFAULT_IMAGE_SIZES,
   HttpClient: () => HttpClient,
+  InMemoryCacheAdapter: () => InMemoryCacheAdapter,
   NewsletterClient: () => NewsletterClient,
   NewsletterManagementClient: () => NewsletterManagementClient,
   NoopCacheAdapter: () => NoopCacheAdapter,
   OrganizationsClient: () => OrganizationsClient,
   PerspectApiClient: () => PerspectApiClient,
+  PerspectApiError: () => PerspectApiError,
   PerspectApiV2Client: () => PerspectApiV2Client,
   PerspectV2Error: () => PerspectV2Error,
   ProductsClient: () => ProductsClient,
@@ -45,9 +47,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,
@@ -65,7 +69,8 @@ __export(index_exports, {
   loadProducts: () => loadProducts,
   transformContent: () => transformContent,
   transformMediaItem: () => transformMediaItem,
-  transformProduct: () => transformProduct
+  transformProduct: () => transformProduct,
+  variantForBucket: () => variantForBucket
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -79,6 +84,20 @@ function warnV1Deprecated() {
   console.warn(`[perspectapi-ts-sdk] ${V1_DEPRECATION_NOTICE}`);
 }
 
+// src/types/index.ts
+var PerspectApiError = class extends Error {
+  code;
+  status;
+  details;
+  constructor({ message, code, status, details }) {
+    super(message);
+    this.name = "PerspectApiError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+
 // src/utils/http-client.ts
 var HttpClient = class {
   baseUrl;
@@ -282,12 +301,12 @@ var HttpClient = class {
     }
     if (!response.ok) {
       console.error(`[HTTP Client - Response] Error response received`);
-      const error = {
+      const error = new PerspectApiError({
         message: data?.error || data?.message || `HTTP ${response.status}: ${response.statusText}`,
         status: response.status,
         code: data?.code,
         details: data
-      };
+      });
       console.error(`[HTTP Client - Response] Throwing error:`, error);
       throw error;
     }
@@ -896,13 +915,29 @@ var CollectionsV2Client = class extends BaseV2Client {
     return this.getOne(this.sitePath(siteName, "collections", id));
   }
   async create(siteName, data) {
-    return this.post(this.sitePath(siteName, "collections"), data);
+    const result = await this.post(this.sitePath(siteName, "collections"), data);
+    await this.invalidateCache({ keys: [this.sitePath(siteName, "collections")] });
+    return result;
   }
   async update(siteName, id, data) {
-    return this.patchOne(this.sitePath(siteName, "collections", id), data);
+    const result = await this.patchOne(this.sitePath(siteName, "collections", id), data);
+    await this.invalidateCache({
+      keys: [
+        this.sitePath(siteName, "collections"),
+        this.sitePath(siteName, "collections", id)
+      ]
+    });
+    return result;
   }
   async del(siteName, id) {
-    return this.deleteOne(this.sitePath(siteName, "collections", id));
+    const result = await this.deleteOne(this.sitePath(siteName, "collections", id));
+    await this.invalidateCache({
+      keys: [
+        this.sitePath(siteName, "collections"),
+        this.sitePath(siteName, "collections", id)
+      ]
+    });
+    return result;
   }
   // --- Items ---
   async listItems(siteName, collectionId) {
@@ -911,15 +946,23 @@ var CollectionsV2Client = class extends BaseV2Client {
     );
   }
   async addItem(siteName, collectionId, data) {
-    return this.post(
+    const result = await this.post(
       this.sitePath(siteName, "collections", `${collectionId}/items`),
       data
     );
+    await this.invalidateCache({
+      keys: [this.sitePath(siteName, "collections", `${collectionId}/items`)]
+    });
+    return result;
   }
   async removeItem(siteName, collectionId, itemId) {
-    return this.deleteOne(
+    const result = await this.deleteOne(
       this.sitePath(siteName, "collections", `${collectionId}/items/${itemId}`)
     );
+    await this.invalidateCache({
+      keys: [this.sitePath(siteName, "collections", `${collectionId}/items`)]
+    });
+    return result;
   }
 };
 
@@ -4139,6 +4182,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: {
@@ -4810,11 +5027,13 @@ async function createCheckoutSession(options) {
   ContentClient,
   DEFAULT_IMAGE_SIZES,
   HttpClient,
+  InMemoryCacheAdapter,
   NewsletterClient,
   NewsletterManagementClient,
   NoopCacheAdapter,
   OrganizationsClient,
   PerspectApiClient,
+  PerspectApiError,
   PerspectApiV2Client,
   PerspectV2Error,
   ProductsClient,
@@ -4823,9 +5042,11 @@ async function createCheckoutSession(options) {
   V1_DEPRECATION_NOTICE,
   V1_SUNSET_DATE,
   WebhooksClient,
+  bucketFor,
   buildImageUrl,
   createApiError,
   createCheckoutSession,
+  createPerspectAb,
   createPerspectApiClient,
   createPerspectApiV2Client,
   generateResponsiveImageHtml,
@@ -4842,5 +5063,6 @@ async function createCheckoutSession(options) {
   loadProducts,
   transformContent,
   transformMediaItem,
-  transformProduct
+  transformProduct,
+  variantForBucket
 });