perspectapi-ts-sdk 2.5.0 → 2.7.0

package/README.md

@@ -147,7 +147,7 @@ export default {
 };
 ```
 
-When PerspectAPI sends a webhook—or when your Worker mutates data directly—call `perspect.cache.invalidate({ tags: [...] })` using the tags emitted by the SDK (`products:site:<site>`, `content:slug:<site>:<slug>`, etc.) so stale entries are purged immediately.
+When PerspectAPI sends a webhook—or when your Worker mutates data directly—call `perspect.cache.invalidate({ tags: [...] })` using the tags emitted by the SDK (`products:site:<site>`, `content:slug:<site>:<slug>`, `content:category:<site>:<category_slug>`, etc.) so stale entries are purged immediately.
 
 ### Webhook-driven cache invalidation
 
@@ -200,6 +200,8 @@ const tagMap: Record<string, (e: WebhookEvent) => string[]> = {
     `categories`,
     `categories:site:${event.site}`,
     `categories:product:${event.site}:${event.slug}`,
+    `products:category:${event.site}:${event.slug}`,
+    `content:category:${event.site}:${event.slug}`,
   ],
 };
 
@@ -392,6 +394,17 @@ const post = await client.content.getContentById(123);
 // Get content by slug
 const page = await client.content.getContentBySlug('your-site-name', 'about-us');
 
+// Get content by category slug
+const categoryContent = await client.content.getContentByCategorySlug(
+  'your-site-name',
+  'news',
+  {
+    page: 1,
+    limit: 20,
+    page_type: 'post'
+  }
+);
+
 // Create new content
 const newPost = await client.content.createContent({
   page_title: 'My New Post',

package/dist/index.d.mts

@@ -312,6 +312,22 @@ interface Category {
     createdAt: string;
     updatedAt: string;
 }
+interface CategorySummary {
+    id: number;
+    name: string;
+    slug: string;
+    description?: string;
+}
+interface ContentCategoryResponse {
+    category: CategorySummary;
+    items: Content[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        pages: number;
+    };
+}
 interface CreateCategoryRequest {
     name: string;
     slug?: string;
@@ -781,6 +797,10 @@ declare class ContentClient extends BaseClient {
      * Get content by ID
      */
     getContentById(id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<Content>>;
+    /**
+     * Get content by category slug for a site
+     */
+    getContentByCategorySlug(siteName: string, categorySlug: string, params?: ContentQueryParams, cachePolicy?: CachePolicy): Promise<ApiResponse<ContentCategoryResponse>>;
     /**
      * Get content by slug for a site
      */
@@ -828,6 +848,11 @@ declare class ContentClient extends BaseClient {
      */
     duplicateContent(id: number): Promise<ApiResponse<Content>>;
     private buildContentTags;
+    /**
+     * Extract the prefix from a slug (first segment before '/')
+     * e.g., 'blog/my-post' -> 'blog', 'about' -> undefined
+     */
+    private extractSlugPrefix;
 }
 
 /**
@@ -1226,6 +1251,11 @@ declare class ProductsClient extends BaseClient {
         };
     }>>;
     private buildProductTags;
+    /**
+     * Extract the prefix from a slug (first segment before '/')
+     * e.g., 'shop/shoes/nike-air' -> 'shop', 'product-name' -> undefined
+     */
+    private extractSlugPrefix;
 }
 
 /**
@@ -2442,4 +2472,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, 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, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, 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 CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };

package/dist/index.d.ts

@@ -312,6 +312,22 @@ interface Category {
     createdAt: string;
     updatedAt: string;
 }
+interface CategorySummary {
+    id: number;
+    name: string;
+    slug: string;
+    description?: string;
+}
+interface ContentCategoryResponse {
+    category: CategorySummary;
+    items: Content[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        pages: number;
+    };
+}
 interface CreateCategoryRequest {
     name: string;
     slug?: string;
@@ -781,6 +797,10 @@ declare class ContentClient extends BaseClient {
      * Get content by ID
      */
     getContentById(id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<Content>>;
+    /**
+     * Get content by category slug for a site
+     */
+    getContentByCategorySlug(siteName: string, categorySlug: string, params?: ContentQueryParams, cachePolicy?: CachePolicy): Promise<ApiResponse<ContentCategoryResponse>>;
     /**
      * Get content by slug for a site
      */
@@ -828,6 +848,11 @@ declare class ContentClient extends BaseClient {
      */
     duplicateContent(id: number): Promise<ApiResponse<Content>>;
     private buildContentTags;
+    /**
+     * Extract the prefix from a slug (first segment before '/')
+     * e.g., 'blog/my-post' -> 'blog', 'about' -> undefined
+     */
+    private extractSlugPrefix;
 }
 
 /**
@@ -1226,6 +1251,11 @@ declare class ProductsClient extends BaseClient {
         };
     }>>;
     private buildProductTags;
+    /**
+     * Extract the prefix from a slug (first segment before '/')
+     * e.g., 'shop/shoes/nike-air' -> 'shop', 'product-name' -> undefined
+     */
+    private extractSlugPrefix;
 }
 
 /**
@@ -2442,4 +2472,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, 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, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, 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 CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };

package/dist/index.js

@@ -902,16 +902,61 @@ var ContentClient = class extends BaseClient {
       () => this.http.get(path)
     );
   }
+  /**
+   * Get content by category slug for a site
+   */
+  async getContentByCategorySlug(siteName, categorySlug, params, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/category/${encodeURIComponent(categorySlug)}`
+    );
+    const path = this.buildPath(endpoint);
+    const normalizedParams = params ? { ...params } : void 0;
+    if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        "content category query"
+      );
+      if (validatedLimit !== void 0) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
+      const validatedPageType = validateOptionalContentType(
+        normalizedParams.page_type,
+        "content category query"
+      );
+      if (validatedPageType !== void 0) {
+        normalizedParams.page_type = validatedPageType;
+      } else {
+        delete normalizedParams.page_type;
+      }
+    }
+    return this.fetchWithCache(
+      endpoint,
+      normalizedParams,
+      this.buildContentTags(
+        siteName,
+        void 0,
+        void 0,
+        normalizedParams?.slug_prefix,
+        categorySlug
+      ),
+      cachePolicy,
+      () => this.http.get(path, normalizedParams)
+    );
+  }
   /**
    * Get content by slug for a site
    */
   async getContentBySlug(siteName, slug, cachePolicy) {
     const endpoint = this.siteScopedEndpoint(siteName, `/slug/${encodeURIComponent(slug)}`);
     const path = this.buildPath(endpoint);
+    const slugPrefix = this.extractSlugPrefix(slug);
     return this.fetchWithCache(
       endpoint,
       void 0,
-      this.buildContentTags(siteName, slug),
+      this.buildContentTags(siteName, slug, void 0, slugPrefix),
       cachePolicy,
       () => this.http.get(path)
     );
@@ -976,7 +1021,7 @@ var ContentClient = class extends BaseClient {
   async duplicateContent(id) {
     return this.create(`/content/${id}/duplicate`, {});
   }
-  buildContentTags(siteName, slug, id, slugPrefix) {
+  buildContentTags(siteName, slug, id, slugPrefix, categorySlug) {
     const tags = /* @__PURE__ */ new Set(["content"]);
     if (siteName) {
       tags.add(`content:site:${siteName}`);
@@ -990,8 +1035,23 @@ var ContentClient = class extends BaseClient {
     if (slugPrefix) {
       tags.add(`content:prefix:${slugPrefix}`);
     }
+    if (categorySlug && siteName) {
+      tags.add("content:category");
+      tags.add(`content:category:${siteName}:${categorySlug}`);
+    }
     return Array.from(tags.values());
   }
+  /**
+   * Extract the prefix from a slug (first segment before '/')
+   * e.g., 'blog/my-post' -> 'blog', 'about' -> undefined
+   */
+  extractSlugPrefix(slug) {
+    const slashIndex = slug.indexOf("/");
+    if (slashIndex > 0) {
+      return slug.substring(0, slashIndex);
+    }
+    return void 0;
+  }
 };
 
 // src/client/api-keys-client.ts
@@ -1277,7 +1337,7 @@ var ProductsClient = class extends BaseClient {
     return this.fetchWithCache(
       endpoint,
       normalizedParams,
-      this.buildProductTags(siteName, ["products:list"]),
+      this.buildProductTags(siteName, ["products:list"], normalizedParams?.slug_prefix),
       cachePolicy,
       () => this.http.get(path, normalizedParams)
     );
@@ -1320,10 +1380,11 @@ var ProductsClient = class extends BaseClient {
       { includeSitesSegment: false }
     );
     const path = this.buildPath(endpoint);
+    const slugPrefix = this.extractSlugPrefix(slug);
     return this.fetchWithCache(
       endpoint,
       void 0,
-      this.buildProductTags(siteName, [`products:slug:${siteName}:${slug}`]),
+      this.buildProductTags(siteName, [`products:slug:${siteName}:${slug}`], slugPrefix),
       cachePolicy,
       () => this.http.get(path)
     );
@@ -1439,14 +1500,28 @@ var ProductsClient = class extends BaseClient {
       () => this.http.get(path, queryParams)
     );
   }
-  buildProductTags(siteName, extraTags = []) {
+  buildProductTags(siteName, extraTags = [], slugPrefix) {
     const tags = /* @__PURE__ */ new Set(["products"]);
     if (siteName) {
       tags.add(`products:site:${siteName}`);
     }
+    if (slugPrefix) {
+      tags.add(`products:prefix:${slugPrefix}`);
+    }
     extraTags.filter(Boolean).forEach((tag) => tags.add(tag));
     return Array.from(tags.values());
   }
+  /**
+   * Extract the prefix from a slug (first segment before '/')
+   * e.g., 'shop/shoes/nike-air' -> 'shop', 'product-name' -> undefined
+   */
+  extractSlugPrefix(slug) {
+    const slashIndex = slug.indexOf("/");
+    if (slashIndex > 0) {
+      return slug.substring(0, slashIndex);
+    }
+    return void 0;
+  }
 };
 
 // src/client/categories-client.ts

package/dist/index.mjs

@@ -841,16 +841,61 @@ var ContentClient = class extends BaseClient {
       () => this.http.get(path)
     );
   }
+  /**
+   * Get content by category slug for a site
+   */
+  async getContentByCategorySlug(siteName, categorySlug, params, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/category/${encodeURIComponent(categorySlug)}`
+    );
+    const path = this.buildPath(endpoint);
+    const normalizedParams = params ? { ...params } : void 0;
+    if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        "content category query"
+      );
+      if (validatedLimit !== void 0) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
+      const validatedPageType = validateOptionalContentType(
+        normalizedParams.page_type,
+        "content category query"
+      );
+      if (validatedPageType !== void 0) {
+        normalizedParams.page_type = validatedPageType;
+      } else {
+        delete normalizedParams.page_type;
+      }
+    }
+    return this.fetchWithCache(
+      endpoint,
+      normalizedParams,
+      this.buildContentTags(
+        siteName,
+        void 0,
+        void 0,
+        normalizedParams?.slug_prefix,
+        categorySlug
+      ),
+      cachePolicy,
+      () => this.http.get(path, normalizedParams)
+    );
+  }
   /**
    * Get content by slug for a site
    */
   async getContentBySlug(siteName, slug, cachePolicy) {
     const endpoint = this.siteScopedEndpoint(siteName, `/slug/${encodeURIComponent(slug)}`);
     const path = this.buildPath(endpoint);
+    const slugPrefix = this.extractSlugPrefix(slug);
     return this.fetchWithCache(
       endpoint,
       void 0,
-      this.buildContentTags(siteName, slug),
+      this.buildContentTags(siteName, slug, void 0, slugPrefix),
       cachePolicy,
       () => this.http.get(path)
     );
@@ -915,7 +960,7 @@ var ContentClient = class extends BaseClient {
   async duplicateContent(id) {
     return this.create(`/content/${id}/duplicate`, {});
   }
-  buildContentTags(siteName, slug, id, slugPrefix) {
+  buildContentTags(siteName, slug, id, slugPrefix, categorySlug) {
     const tags = /* @__PURE__ */ new Set(["content"]);
     if (siteName) {
       tags.add(`content:site:${siteName}`);
@@ -929,8 +974,23 @@ var ContentClient = class extends BaseClient {
     if (slugPrefix) {
       tags.add(`content:prefix:${slugPrefix}`);
     }
+    if (categorySlug && siteName) {
+      tags.add("content:category");
+      tags.add(`content:category:${siteName}:${categorySlug}`);
+    }
     return Array.from(tags.values());
   }
+  /**
+   * Extract the prefix from a slug (first segment before '/')
+   * e.g., 'blog/my-post' -> 'blog', 'about' -> undefined
+   */
+  extractSlugPrefix(slug) {
+    const slashIndex = slug.indexOf("/");
+    if (slashIndex > 0) {
+      return slug.substring(0, slashIndex);
+    }
+    return void 0;
+  }
 };
 
 // src/client/api-keys-client.ts
@@ -1216,7 +1276,7 @@ var ProductsClient = class extends BaseClient {
     return this.fetchWithCache(
       endpoint,
       normalizedParams,
-      this.buildProductTags(siteName, ["products:list"]),
+      this.buildProductTags(siteName, ["products:list"], normalizedParams?.slug_prefix),
       cachePolicy,
       () => this.http.get(path, normalizedParams)
     );
@@ -1259,10 +1319,11 @@ var ProductsClient = class extends BaseClient {
       { includeSitesSegment: false }
     );
     const path = this.buildPath(endpoint);
+    const slugPrefix = this.extractSlugPrefix(slug);
     return this.fetchWithCache(
       endpoint,
       void 0,
-      this.buildProductTags(siteName, [`products:slug:${siteName}:${slug}`]),
+      this.buildProductTags(siteName, [`products:slug:${siteName}:${slug}`], slugPrefix),
       cachePolicy,
       () => this.http.get(path)
     );
@@ -1378,14 +1439,28 @@ var ProductsClient = class extends BaseClient {
       () => this.http.get(path, queryParams)
     );
   }
-  buildProductTags(siteName, extraTags = []) {
+  buildProductTags(siteName, extraTags = [], slugPrefix) {
     const tags = /* @__PURE__ */ new Set(["products"]);
     if (siteName) {
       tags.add(`products:site:${siteName}`);
     }
+    if (slugPrefix) {
+      tags.add(`products:prefix:${slugPrefix}`);
+    }
     extraTags.filter(Boolean).forEach((tag) => tags.add(tag));
     return Array.from(tags.values());
   }
+  /**
+   * Extract the prefix from a slug (first segment before '/')
+   * e.g., 'shop/shoes/nike-air' -> 'shop', 'product-name' -> undefined
+   */
+  extractSlugPrefix(slug) {
+    const slashIndex = slug.indexOf("/");
+    if (slashIndex > 0) {
+      return slug.substring(0, slashIndex);
+    }
+    return void 0;
+  }
 };
 
 // src/client/categories-client.ts

package/package.json

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

package/src/client/content-client.ts

@@ -12,6 +12,7 @@ import type {
   ContentQueryParams,
   PaginatedResponse,
   ApiResponse,
+  ContentCategoryResponse,
 } from '../types';
 import { validateOptionalContentType, validateOptionalLimit } from '../utils/validators';
 
@@ -139,6 +140,61 @@ export class ContentClient extends BaseClient {
     );
   }
 
+  /**
+   * Get content by category slug for a site
+   */
+  async getContentByCategorySlug(
+    siteName: string,
+    categorySlug: string,
+    params?: ContentQueryParams,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<ContentCategoryResponse>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/category/${encodeURIComponent(categorySlug)}`
+    );
+    const path = this.buildPath(endpoint);
+    const normalizedParams: ContentQueryParams | undefined = params
+      ? { ...params }
+      : undefined;
+
+    if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        'content category query',
+      );
+      if (validatedLimit !== undefined) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
+
+      const validatedPageType = validateOptionalContentType(
+        normalizedParams.page_type,
+        'content category query',
+      );
+      if (validatedPageType !== undefined) {
+        normalizedParams.page_type = validatedPageType;
+      } else {
+        delete normalizedParams.page_type;
+      }
+    }
+
+    return this.fetchWithCache<ApiResponse<ContentCategoryResponse>>(
+      endpoint,
+      normalizedParams,
+      this.buildContentTags(
+        siteName,
+        undefined,
+        undefined,
+        normalizedParams?.slug_prefix,
+        categorySlug
+      ),
+      cachePolicy,
+      () => this.http.get<ContentCategoryResponse>(path, normalizedParams)
+    );
+  }
+
   /**
    * Get content by slug for a site
    */
@@ -149,11 +205,12 @@ export class ContentClient extends BaseClient {
   ): Promise<ApiResponse<Content>> {
     const endpoint = this.siteScopedEndpoint(siteName, `/slug/${encodeURIComponent(slug)}`);
     const path = this.buildPath(endpoint);
+    const slugPrefix = this.extractSlugPrefix(slug);
 
     return this.fetchWithCache<ApiResponse<Content>>(
       endpoint,
       undefined,
-      this.buildContentTags(siteName, slug),
+      this.buildContentTags(siteName, slug, undefined, slugPrefix),
       cachePolicy,
       () => this.http.get<Content>(path)
     );
@@ -229,7 +286,13 @@ export class ContentClient extends BaseClient {
     return this.create<Record<string, never>, Content>(`/content/${id}/duplicate`, {});
   }
 
-  private buildContentTags(siteName?: string, slug?: string, id?: number, slugPrefix?: string): string[] {
+  private buildContentTags(
+    siteName?: string,
+    slug?: string,
+    id?: number,
+    slugPrefix?: string,
+    categorySlug?: string
+  ): string[] {
     const tags = new Set<string>(['content']);
     if (siteName) {
       tags.add(`content:site:${siteName}`);
@@ -243,6 +306,22 @@ export class ContentClient extends BaseClient {
     if (slugPrefix) {
       tags.add(`content:prefix:${slugPrefix}`);
     }
+    if (categorySlug && siteName) {
+      tags.add('content:category');
+      tags.add(`content:category:${siteName}:${categorySlug}`);
+    }
     return Array.from(tags.values());
   }
+
+  /**
+   * Extract the prefix from a slug (first segment before '/')
+   * e.g., 'blog/my-post' -> 'blog', 'about' -> undefined
+   */
+  private extractSlugPrefix(slug: string): string | undefined {
+    const slashIndex = slug.indexOf('/');
+    if (slashIndex > 0) {
+      return slug.substring(0, slashIndex);
+    }
+    return undefined;
+  }
 }

package/src/client/products-client.ts

@@ -73,7 +73,7 @@ export class ProductsClient extends BaseClient {
     return this.fetchWithCache<PaginatedResponse<Product>>(
       endpoint,
       normalizedParams,
-      this.buildProductTags(siteName, ['products:list']),
+      this.buildProductTags(siteName, ['products:list'], normalizedParams?.slug_prefix),
       cachePolicy,
       () => this.http.get(path, normalizedParams) as Promise<PaginatedResponse<Product>>
     );
@@ -125,11 +125,12 @@ export class ProductsClient extends BaseClient {
       { includeSitesSegment: false }
     );
     const path = this.buildPath(endpoint);
+    const slugPrefix = this.extractSlugPrefix(slug);
 
     return this.fetchWithCache<ApiResponse<Product & { variants?: any[] }>>(
       endpoint,
       undefined,
-      this.buildProductTags(siteName, [`products:slug:${siteName}:${slug}`]),
+      this.buildProductTags(siteName, [`products:slug:${siteName}:${slug}`], slugPrefix),
       cachePolicy,
       () => this.http.get<Product & { variants?: any[] }>(path)
     );
@@ -347,12 +348,27 @@ export class ProductsClient extends BaseClient {
     );
   }
 
-  private buildProductTags(siteName?: string, extraTags: string[] = []): string[] {
+  private buildProductTags(siteName?: string, extraTags: string[] = [], slugPrefix?: string): string[] {
     const tags = new Set<string>(['products']);
     if (siteName) {
       tags.add(`products:site:${siteName}`);
     }
+    if (slugPrefix) {
+      tags.add(`products:prefix:${slugPrefix}`);
+    }
     extraTags.filter(Boolean).forEach(tag => tags.add(tag));
     return Array.from(tags.values());
   }
+
+  /**
+   * Extract the prefix from a slug (first segment before '/')
+   * e.g., 'shop/shoes/nike-air' -> 'shop', 'product-name' -> undefined
+   */
+  private extractSlugPrefix(slug: string): string | undefined {
+    const slashIndex = slug.indexOf('/');
+    if (slashIndex > 0) {
+      return slug.substring(0, slashIndex);
+    }
+    return undefined;
+  }
 }

package/src/index.ts

@@ -80,12 +80,14 @@ export type {
   PaginatedResponse,
   ApiError,
   User,
-  Content,
+  Content, 
+  ContentCategoryResponse,
   Product,
   ProductQueryParams,
   MediaItem,
   BlogPost,
   Category,
+  CategorySummary,
   Organization,
   Site,
   ApiKey,

package/src/types/index.ts

@@ -268,6 +268,24 @@ export interface Category {
   updatedAt: string;
 }
 
+export interface CategorySummary {
+  id: number;
+  name: string;
+  slug: string;
+  description?: string;
+}
+
+export interface ContentCategoryResponse {
+  category: CategorySummary;
+  items: Content[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    pages: number;
+  };
+}
+
 export interface CreateCategoryRequest {
   name: string;
   slug?: string;