perspectapi-ts-sdk 5.0.3 → 5.1.0

package/dist/index.d.mts

@@ -3410,7 +3410,7 @@ interface V2WebhookUpdateParams extends Partial<V2WebhookCreateParams> {
 }
 
 /**
- * v2 Base Client — cursor pagination, expand support, typed errors.
+ * v2 Base Client — cursor pagination, expand support, caching, typed errors.
  */
 
 declare class PerspectV2Error extends Error {
@@ -3423,7 +3423,8 @@ declare class PerspectV2Error extends Error {
 declare abstract class BaseV2Client {
     protected http: HttpClient;
     protected basePath: string;
-    constructor(http: HttpClient, basePath: string);
+    protected cache?: CacheManager;
+    constructor(http: HttpClient, basePath: string, cache?: CacheManager);
     protected buildPath(endpoint: string): string;
     protected sitePath(siteName: string, resource: string, suffix?: string): string;
     private toParams;
@@ -3439,16 +3440,21 @@ declare abstract class BaseV2Client {
      * We unwrap accordingly.
      */
     private extractData;
-    /** GET a single resource. */
-    protected getOne<T>(path: string, params?: object): Promise<T>;
-    /** GET a list of resources with cursor pagination. */
-    protected getList<T>(path: string, params?: object): Promise<V2List<T>>;
+    /** GET a single resource, with optional caching. */
+    protected getOne<T>(path: string, params?: object, cachePolicy?: CachePolicy): Promise<T>;
+    /** GET a list of resources with cursor pagination, with optional caching. */
+    protected getList<T>(path: string, params?: object, cachePolicy?: CachePolicy): Promise<V2List<T>>;
     /** POST to create a resource. */
     protected post<T>(path: string, body?: unknown): Promise<T>;
     /** PATCH to update a resource. */
     protected patchOne<T>(path: string, body?: unknown): Promise<T>;
     /** DELETE a resource. */
     protected deleteOne(path: string): Promise<V2Deleted>;
+    /** Fetch with optional cache. Bypasses cache for writes or when no cache is configured. */
+    private fetchWithCache;
+    /** Invalidate cache entries by keys or tags. */
+    protected invalidateCache(options: CacheInvalidateOptions): Promise<void>;
+    private buildCacheKey;
     /**
      * Auto-paginating async generator.
      * Yields every item across all pages.
@@ -3467,9 +3473,9 @@ declare abstract class BaseV2Client {
  */
 
 declare class ContentV2Client extends BaseV2Client {
-    list(siteName: string, params?: V2ContentListParams): Promise<V2List<V2Content>>;
+    list(siteName: string, params?: V2ContentListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Content>>;
     listAutoPaginated(siteName: string, params?: Omit<V2ContentListParams, 'starting_after' | 'ending_before'>): AsyncGenerator<V2Content, void, unknown>;
-    get(siteName: string, idOrSlug: string): Promise<V2Content>;
+    get(siteName: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2Content>;
     create(siteName: string, data: V2ContentCreateParams): Promise<V2Content>;
     update(siteName: string, id: string, data: V2ContentUpdateParams): Promise<V2Content>;
     del(siteName: string, id: string): Promise<V2Deleted>;
@@ -3482,9 +3488,9 @@ declare class ContentV2Client extends BaseV2Client {
  */
 
 declare class ProductsV2Client extends BaseV2Client {
-    list(siteName: string, params?: V2ProductListParams): Promise<V2List<V2Product>>;
+    list(siteName: string, params?: V2ProductListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Product>>;
     listAutoPaginated(siteName: string, params?: Omit<V2ProductListParams, 'starting_after' | 'ending_before'>): AsyncGenerator<V2Product, void, unknown>;
-    get(siteName: string, idOrSlug: string): Promise<V2Product>;
+    get(siteName: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2Product>;
     create(siteName: string, data: V2ProductCreateParams): Promise<V2Product>;
     update(siteName: string, id: string, data: V2ProductUpdateParams): Promise<V2Product>;
     del(siteName: string, id: string): Promise<V2Deleted>;
@@ -3497,8 +3503,8 @@ declare class ProductsV2Client extends BaseV2Client {
 declare class CategoriesV2Client extends BaseV2Client {
     list(siteName: string, params?: V2PaginationParams & {
         type?: string;
-    }): Promise<V2List<V2Category>>;
-    get(siteName: string, id: string): Promise<V2Category>;
+    }, cachePolicy?: CachePolicy): Promise<V2List<V2Category>>;
+    get(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2Category>;
     create(siteName: string, data: V2CategoryCreateParams): Promise<V2Category>;
     update(siteName: string, id: string, data: V2CategoryUpdateParams): Promise<V2Category>;
     del(siteName: string, id: string): Promise<V2Deleted>;
@@ -3529,9 +3535,9 @@ declare class CollectionsV2Client extends BaseV2Client {
  */
 
 declare class OrdersV2Client extends BaseV2Client {
-    list(siteName: string, params?: V2OrderListParams): Promise<V2List<V2Order>>;
+    list(siteName: string, params?: V2OrderListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Order>>;
     listAutoPaginated(siteName: string, params?: Omit<V2OrderListParams, 'starting_after' | 'ending_before'>): AsyncGenerator<V2Order, void, unknown>;
-    get(siteName: string, id: string): Promise<V2Order>;
+    get(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2Order>;
 }
 
 /**
@@ -3588,13 +3594,13 @@ declare class NewsletterV2Client extends BaseV2Client {
     trackClick(siteName: string, token: string, url: string): Promise<V2NewsletterTrackingResponse>;
     listSubscriptions(siteName: string, params?: V2PaginationParams & {
         status?: string;
-    }): Promise<V2List<V2NewsletterSubscription>>;
-    getSubscription(siteName: string, id: string): Promise<V2NewsletterSubscription>;
-    listLists(siteName: string): Promise<V2List<V2NewsletterList>>;
+    }, cachePolicy?: CachePolicy): Promise<V2List<V2NewsletterSubscription>>;
+    getSubscription(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2NewsletterSubscription>;
+    listLists(siteName: string, cachePolicy?: CachePolicy): Promise<V2List<V2NewsletterList>>;
     listCampaigns(siteName: string, params?: V2PaginationParams & {
         status?: string;
-    }): Promise<V2List<V2NewsletterCampaign>>;
-    getCampaign(siteName: string, idOrSlug: string): Promise<V2NewsletterCampaign>;
+    }, cachePolicy?: CachePolicy): Promise<V2List<V2NewsletterCampaign>>;
+    getCampaign(siteName: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2NewsletterCampaign>;
 }
 
 /**
@@ -3671,8 +3677,12 @@ declare class WebhooksV2Client extends BaseV2Client {
  *   const posts = await client.content.list('mysite', { type: 'post', limit: 10 });
  */
 
+interface PerspectApiV2Config extends PerspectApiConfig {
+    cache?: CacheConfig;
+}
 declare class PerspectApiV2Client {
     private http;
+    readonly cache: CacheManager;
     readonly content: ContentV2Client;
     readonly products: ProductsV2Client;
     readonly categories: CategoriesV2Client;
@@ -3685,7 +3695,7 @@ declare class PerspectApiV2Client {
     readonly sites: SitesV2Client;
     readonly apiKeys: ApiKeysV2Client;
     readonly webhooks: WebhooksV2Client;
-    constructor(config: PerspectApiConfig);
+    constructor(config: PerspectApiV2Config);
     /** Update the JWT token for authenticated requests. */
     setAuth(jwt: string): void;
     /** Update the API key. */
@@ -3695,6 +3705,42 @@ declare class PerspectApiV2Client {
 }
 declare function createPerspectApiV2Client(config: PerspectApiConfig): PerspectApiV2Client;
 
+/**
+ * Adapter that bridges a CacheStorage-compatible KV implementation
+ * (e.g. CloudflareKvAdapter from @perspect/shared) to the SDK's CacheAdapter interface.
+ *
+ * Usage:
+ *   import { CloudflareKvAdapter } from '@perspect/shared';
+ *   import { CloudflareKVCacheAdapter } from 'perspectapi-ts-sdk';
+ *
+ *   const kvAdapter = new CloudflareKvAdapter(env.CACHE_KV);
+ *   const cacheAdapter = new CloudflareKVCacheAdapter(kvAdapter);
+ *
+ * Or pass any object with get/put/delete methods matching Cloudflare KV semantics.
+ */
+
+/** Minimal interface matching CloudflareKvAdapter / CacheStorage from @perspect/shared. */
+interface KVLike {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteMultiple?(keys: string[]): Promise<void>;
+    clear?(): Promise<void>;
+}
+declare class CloudflareKVCacheAdapter implements CacheAdapter {
+    private kv;
+    constructor(kv: KVLike);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteMany(keys: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
 /**
  * Simple in-memory cache adapter primarily suited for development and testing.
  */
@@ -4013,4 +4059,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, 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, InMemoryCacheAdapter, 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, 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 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, InMemoryCacheAdapter, 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, 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 };

package/dist/index.d.ts

@@ -3410,7 +3410,7 @@ interface V2WebhookUpdateParams extends Partial<V2WebhookCreateParams> {
 }
 
 /**
- * v2 Base Client — cursor pagination, expand support, typed errors.
+ * v2 Base Client — cursor pagination, expand support, caching, typed errors.
  */
 
 declare class PerspectV2Error extends Error {
@@ -3423,7 +3423,8 @@ declare class PerspectV2Error extends Error {
 declare abstract class BaseV2Client {
     protected http: HttpClient;
     protected basePath: string;
-    constructor(http: HttpClient, basePath: string);
+    protected cache?: CacheManager;
+    constructor(http: HttpClient, basePath: string, cache?: CacheManager);
     protected buildPath(endpoint: string): string;
     protected sitePath(siteName: string, resource: string, suffix?: string): string;
     private toParams;
@@ -3439,16 +3440,21 @@ declare abstract class BaseV2Client {
      * We unwrap accordingly.
      */
     private extractData;
-    /** GET a single resource. */
-    protected getOne<T>(path: string, params?: object): Promise<T>;
-    /** GET a list of resources with cursor pagination. */
-    protected getList<T>(path: string, params?: object): Promise<V2List<T>>;
+    /** GET a single resource, with optional caching. */
+    protected getOne<T>(path: string, params?: object, cachePolicy?: CachePolicy): Promise<T>;
+    /** GET a list of resources with cursor pagination, with optional caching. */
+    protected getList<T>(path: string, params?: object, cachePolicy?: CachePolicy): Promise<V2List<T>>;
     /** POST to create a resource. */
     protected post<T>(path: string, body?: unknown): Promise<T>;
     /** PATCH to update a resource. */
     protected patchOne<T>(path: string, body?: unknown): Promise<T>;
     /** DELETE a resource. */
     protected deleteOne(path: string): Promise<V2Deleted>;
+    /** Fetch with optional cache. Bypasses cache for writes or when no cache is configured. */
+    private fetchWithCache;
+    /** Invalidate cache entries by keys or tags. */
+    protected invalidateCache(options: CacheInvalidateOptions): Promise<void>;
+    private buildCacheKey;
     /**
      * Auto-paginating async generator.
      * Yields every item across all pages.
@@ -3467,9 +3473,9 @@ declare abstract class BaseV2Client {
  */
 
 declare class ContentV2Client extends BaseV2Client {
-    list(siteName: string, params?: V2ContentListParams): Promise<V2List<V2Content>>;
+    list(siteName: string, params?: V2ContentListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Content>>;
     listAutoPaginated(siteName: string, params?: Omit<V2ContentListParams, 'starting_after' | 'ending_before'>): AsyncGenerator<V2Content, void, unknown>;
-    get(siteName: string, idOrSlug: string): Promise<V2Content>;
+    get(siteName: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2Content>;
     create(siteName: string, data: V2ContentCreateParams): Promise<V2Content>;
     update(siteName: string, id: string, data: V2ContentUpdateParams): Promise<V2Content>;
     del(siteName: string, id: string): Promise<V2Deleted>;
@@ -3482,9 +3488,9 @@ declare class ContentV2Client extends BaseV2Client {
  */
 
 declare class ProductsV2Client extends BaseV2Client {
-    list(siteName: string, params?: V2ProductListParams): Promise<V2List<V2Product>>;
+    list(siteName: string, params?: V2ProductListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Product>>;
     listAutoPaginated(siteName: string, params?: Omit<V2ProductListParams, 'starting_after' | 'ending_before'>): AsyncGenerator<V2Product, void, unknown>;
-    get(siteName: string, idOrSlug: string): Promise<V2Product>;
+    get(siteName: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2Product>;
     create(siteName: string, data: V2ProductCreateParams): Promise<V2Product>;
     update(siteName: string, id: string, data: V2ProductUpdateParams): Promise<V2Product>;
     del(siteName: string, id: string): Promise<V2Deleted>;
@@ -3497,8 +3503,8 @@ declare class ProductsV2Client extends BaseV2Client {
 declare class CategoriesV2Client extends BaseV2Client {
     list(siteName: string, params?: V2PaginationParams & {
         type?: string;
-    }): Promise<V2List<V2Category>>;
-    get(siteName: string, id: string): Promise<V2Category>;
+    }, cachePolicy?: CachePolicy): Promise<V2List<V2Category>>;
+    get(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2Category>;
     create(siteName: string, data: V2CategoryCreateParams): Promise<V2Category>;
     update(siteName: string, id: string, data: V2CategoryUpdateParams): Promise<V2Category>;
     del(siteName: string, id: string): Promise<V2Deleted>;
@@ -3529,9 +3535,9 @@ declare class CollectionsV2Client extends BaseV2Client {
  */
 
 declare class OrdersV2Client extends BaseV2Client {
-    list(siteName: string, params?: V2OrderListParams): Promise<V2List<V2Order>>;
+    list(siteName: string, params?: V2OrderListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Order>>;
     listAutoPaginated(siteName: string, params?: Omit<V2OrderListParams, 'starting_after' | 'ending_before'>): AsyncGenerator<V2Order, void, unknown>;
-    get(siteName: string, id: string): Promise<V2Order>;
+    get(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2Order>;
 }
 
 /**
@@ -3588,13 +3594,13 @@ declare class NewsletterV2Client extends BaseV2Client {
     trackClick(siteName: string, token: string, url: string): Promise<V2NewsletterTrackingResponse>;
     listSubscriptions(siteName: string, params?: V2PaginationParams & {
         status?: string;
-    }): Promise<V2List<V2NewsletterSubscription>>;
-    getSubscription(siteName: string, id: string): Promise<V2NewsletterSubscription>;
-    listLists(siteName: string): Promise<V2List<V2NewsletterList>>;
+    }, cachePolicy?: CachePolicy): Promise<V2List<V2NewsletterSubscription>>;
+    getSubscription(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2NewsletterSubscription>;
+    listLists(siteName: string, cachePolicy?: CachePolicy): Promise<V2List<V2NewsletterList>>;
     listCampaigns(siteName: string, params?: V2PaginationParams & {
         status?: string;
-    }): Promise<V2List<V2NewsletterCampaign>>;
-    getCampaign(siteName: string, idOrSlug: string): Promise<V2NewsletterCampaign>;
+    }, cachePolicy?: CachePolicy): Promise<V2List<V2NewsletterCampaign>>;
+    getCampaign(siteName: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2NewsletterCampaign>;
 }
 
 /**
@@ -3671,8 +3677,12 @@ declare class WebhooksV2Client extends BaseV2Client {
  *   const posts = await client.content.list('mysite', { type: 'post', limit: 10 });
  */
 
+interface PerspectApiV2Config extends PerspectApiConfig {
+    cache?: CacheConfig;
+}
 declare class PerspectApiV2Client {
     private http;
+    readonly cache: CacheManager;
     readonly content: ContentV2Client;
     readonly products: ProductsV2Client;
     readonly categories: CategoriesV2Client;
@@ -3685,7 +3695,7 @@ declare class PerspectApiV2Client {
     readonly sites: SitesV2Client;
     readonly apiKeys: ApiKeysV2Client;
     readonly webhooks: WebhooksV2Client;
-    constructor(config: PerspectApiConfig);
+    constructor(config: PerspectApiV2Config);
     /** Update the JWT token for authenticated requests. */
     setAuth(jwt: string): void;
     /** Update the API key. */
@@ -3695,6 +3705,42 @@ declare class PerspectApiV2Client {
 }
 declare function createPerspectApiV2Client(config: PerspectApiConfig): PerspectApiV2Client;
 
+/**
+ * Adapter that bridges a CacheStorage-compatible KV implementation
+ * (e.g. CloudflareKvAdapter from @perspect/shared) to the SDK's CacheAdapter interface.
+ *
+ * Usage:
+ *   import { CloudflareKvAdapter } from '@perspect/shared';
+ *   import { CloudflareKVCacheAdapter } from 'perspectapi-ts-sdk';
+ *
+ *   const kvAdapter = new CloudflareKvAdapter(env.CACHE_KV);
+ *   const cacheAdapter = new CloudflareKVCacheAdapter(kvAdapter);
+ *
+ * Or pass any object with get/put/delete methods matching Cloudflare KV semantics.
+ */
+
+/** Minimal interface matching CloudflareKvAdapter / CacheStorage from @perspect/shared. */
+interface KVLike {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteMultiple?(keys: string[]): Promise<void>;
+    clear?(): Promise<void>;
+}
+declare class CloudflareKVCacheAdapter implements CacheAdapter {
+    private kv;
+    constructor(kv: KVLike);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteMany(keys: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
 /**
  * Simple in-memory cache adapter primarily suited for development and testing.
  */
@@ -4013,4 +4059,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, 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, InMemoryCacheAdapter, 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, 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 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, InMemoryCacheAdapter, 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, 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 };