perspectapi-ts-sdk 2.6.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
      */
@@ -2452,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
      */
@@ -2452,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,6 +902,50 @@ 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
    */
@@ -977,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}`);
@@ -991,6 +1035,10 @@ 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());
   }
   /**

package/dist/index.mjs

@@ -841,6 +841,50 @@ 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
    */
@@ -916,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}`);
@@ -930,6 +974,10 @@ 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());
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "2.6.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
    */
@@ -230,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}`);
@@ -244,6 +306,10 @@ 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());
   }
 

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;