perspectapi-ts-sdk 2.8.2 → 2.9.0

package/README.md

@@ -13,6 +13,7 @@ A comprehensive TypeScript SDK for PerspectAPI, designed to work seamlessly with
 - 📊 **Comprehensive Coverage** - All PerspectAPI endpoints supported
 - 🧩 **High-Level Loaders** - Drop-in helpers for products, content, and checkout flows with fallbacks
 - 📧 **Newsletter Management** - Complete newsletter subscription system with double opt-in, preferences, and lists
+- 👥 **Site Users** - OTP-based customer accounts with metadata, profiles, orders, and subscriptions
 
 ## Installation
 
@@ -734,6 +735,100 @@ console.log('Imported:', importResult.data.imported);
 console.log('Failed:', importResult.data.failed);
 ```
 
+> 📚 **For complete newsletter documentation**, see [docs/newsletter.md](docs/newsletter.md)
+
+### Site Users (Customer Accounts)
+
+Site users are per-site customer accounts with OTP-based authentication, separate from admin users.
+
+```typescript
+const siteName = 'your-site-name';
+
+// Request OTP for login/signup (with optional metadata)
+await client.siteUsers.requestOtp(
+  siteName,
+  {
+    email: 'user@example.com',
+    waitlist: true,  // Optional: mark as waitlist signup
+    metadata: {      // Optional: set metadata at signup time
+      signupSource: 'landing-page',
+      referralCode: 'FRIEND123',
+      interests: ['product-updates']
+    }
+  },
+  csrfToken
+);
+
+// Verify OTP and get JWT token
+const response = await client.siteUsers.verifyOtp(
+  siteName,
+  { email: 'user@example.com', code: '123456' },
+  csrfToken
+);
+
+const { token, user } = response.data;
+client.setAuth(token);  // Set auth for subsequent requests
+
+// Get current user profile
+const { data } = await client.siteUsers.getMe(siteName);
+console.log(data.user);      // Basic user fields + metadata
+console.log(data.profile);   // Key-value profile data
+
+// Update user profile and metadata
+await client.siteUsers.updateMe(
+  siteName,
+  {
+    first_name: 'John',
+    last_name: 'Doe',
+    metadata: {
+      preferences: { theme: 'dark' },
+      tags: ['premium'],
+      customField: 'value'
+    }
+  },
+  csrfToken
+);
+
+// Set profile key-values (phone, addresses, etc.)
+await client.siteUsers.setProfileValue(
+  siteName,
+  'phone',
+  '+1-555-0123',
+  csrfToken
+);
+
+await client.siteUsers.setProfileValue(
+  siteName,
+  'address_shipping',
+  JSON.stringify({
+    line1: '123 Main St',
+    city: 'San Francisco',
+    state: 'CA',
+    postal_code: '94102',
+    country: 'US'
+  }),
+  csrfToken
+);
+
+// Get order history
+const orders = await client.siteUsers.getOrders(siteName, {
+  limit: 50,
+  offset: 0
+});
+
+// Get subscriptions
+const subscriptions = await client.siteUsers.getSubscriptions(siteName);
+
+// Cancel subscription
+await client.siteUsers.cancelSubscription(siteName, 'sub_123', csrfToken);
+
+// Logout
+await client.siteUsers.logout(siteName);
+client.setAuth(null);
+```
+
+> 📚 **For complete site users documentation** including waitlist management, metadata patterns, cross-domain authentication, and complete examples, see [docs/site-users.md](docs/site-users.md)
+
 ## Configuration Options
 
 ```typescript

package/dist/index.d.mts

@@ -627,6 +627,7 @@ interface SiteUserOrder {
 interface RequestOtpRequest {
     email: string;
     waitlist?: boolean;
+    metadata?: Record<string, any>;
 }
 interface VerifyOtpRequest {
     email: string;
@@ -1410,95 +1411,66 @@ declare class ProductsClient extends BaseClient {
 declare class CategoriesClient extends BaseClient {
     constructor(http: any, cache?: CacheManager);
     /**
-     * Get all categories
-     */
-    getCategories(params?: {
-        page?: number;
-        limit?: number;
-        parentId?: number;
-        organizationId?: number;
-    }): Promise<PaginatedResponse<Category>>;
-    /**
-     * Get category by ID
+     * Get all categories for a site
      */
-    getCategoryById(id: number): Promise<ApiResponse<Category>>;
-    /**
-     * Get category by slug
-     */
-    getCategoryBySlug(slug: string): Promise<ApiResponse<Category>>;
-    /**
-     * Get product category by slug (for products)
-     */
-    getProductCategoryBySlug(siteName: string, slug: string, cachePolicy?: CachePolicy): Promise<ApiResponse<Category>>;
+    getCategories(siteName: string, params?: {
+        category_type?: 'post' | 'product';
+        parent_id?: string;
+        include_subcategories?: 'true' | 'false';
+    }, cachePolicy?: CachePolicy): Promise<ApiResponse<{
+        categories: Category[];
+    }>>;
     /**
-     * Create new category
+     * Get category by ID (validates it belongs to the site)
      */
-    createCategory(data: CreateCategoryRequest): Promise<ApiResponse<Category>>;
+    getCategoryById(siteName: string, id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<{
+        category: Category;
+    }>>;
     /**
-     * Update category
+     * Get product categories for a site
      */
-    updateCategory(id: number, data: Partial<CreateCategoryRequest>): Promise<ApiResponse<Category>>;
+    getProductCategories(siteName: string, params?: {
+        parent_id?: string;
+        include_subcategories?: 'true' | 'false';
+    }, cachePolicy?: CachePolicy): Promise<ApiResponse<{
+        categories: Category[];
+    }>>;
     /**
-     * Delete category
+     * Create new category for a site
      */
-    deleteCategory(id: number): Promise<ApiResponse<{
+    createCategory(siteName: string, data: CreateCategoryRequest, csrfToken?: string): Promise<ApiResponse<{
         message: string;
+        category_id: number;
     }>>;
     /**
-     * Get category tree (hierarchical structure)
-     */
-    getCategoryTree(rootId?: number): Promise<ApiResponse<Array<Category & {
-        children: Category[];
-    }>>>;
-    /**
-     * Get category children
+     * Create new product category for a site
      */
-    getCategoryChildren(id: number): Promise<ApiResponse<Category[]>>;
-    /**
-     * Get category parent
-     */
-    getCategoryParent(id: number): Promise<ApiResponse<Category | null>>;
-    /**
-     * Move category to new parent
-     */
-    moveCategoryToParent(id: number, parentId: number | null): Promise<ApiResponse<Category>>;
-    /**
-     * Get category breadcrumb path
-     */
-    getCategoryBreadcrumb(id: number): Promise<ApiResponse<Array<{
-        id: number;
-        name: string;
-        slug: string;
-    }>>>;
+    createProductCategory(siteName: string, data: Omit<CreateCategoryRequest, 'category_type'>, csrfToken?: string): Promise<ApiResponse<{
+        message: string;
+        category_id: number;
+    }>>;
     /**
-     * Get category content/products
+     * Update category (validates it belongs to the site)
      */
-    getCategoryContent(id: number, params?: {
-        page?: number;
-        limit?: number;
-        type?: 'content' | 'products' | 'all';
-    }): Promise<ApiResponse<{
-        content: any[];
-        products: any[];
-        total: number;
+    updateCategory(siteName: string, id: number, data: Partial<CreateCategoryRequest>, csrfToken?: string): Promise<ApiResponse<{
+        message: string;
     }>>;
     /**
-     * Bulk update category order
+     * Delete category (validates it belongs to the site)
      */
-    updateCategoryOrder(updates: Array<{
-        id: number;
-        order: number;
-        parentId?: number;
-    }>): Promise<ApiResponse<{
+    deleteCategory(siteName: string, id: number, csrfToken?: string): Promise<ApiResponse<{
         message: string;
     }>>;
     /**
-     * Search categories
+     * Associate pages or products with categories
      */
-    searchCategories(query: string, params?: {
-        limit?: number;
-        organizationId?: number;
-    }): Promise<ApiResponse<Category[]>>;
+    associateCategories(siteName: string, data: {
+        entity_id: number;
+        entity_type: 'page' | 'product';
+        category_ids: number[];
+    }, csrfToken?: string): Promise<ApiResponse<{
+        message: string;
+    }>>;
     private buildCategoryTags;
 }
 

package/dist/index.d.ts

@@ -627,6 +627,7 @@ interface SiteUserOrder {
 interface RequestOtpRequest {
     email: string;
     waitlist?: boolean;
+    metadata?: Record<string, any>;
 }
 interface VerifyOtpRequest {
     email: string;
@@ -1410,95 +1411,66 @@ declare class ProductsClient extends BaseClient {
 declare class CategoriesClient extends BaseClient {
     constructor(http: any, cache?: CacheManager);
     /**
-     * Get all categories
-     */
-    getCategories(params?: {
-        page?: number;
-        limit?: number;
-        parentId?: number;
-        organizationId?: number;
-    }): Promise<PaginatedResponse<Category>>;
-    /**
-     * Get category by ID
+     * Get all categories for a site
      */
-    getCategoryById(id: number): Promise<ApiResponse<Category>>;
-    /**
-     * Get category by slug
-     */
-    getCategoryBySlug(slug: string): Promise<ApiResponse<Category>>;
-    /**
-     * Get product category by slug (for products)
-     */
-    getProductCategoryBySlug(siteName: string, slug: string, cachePolicy?: CachePolicy): Promise<ApiResponse<Category>>;
+    getCategories(siteName: string, params?: {
+        category_type?: 'post' | 'product';
+        parent_id?: string;
+        include_subcategories?: 'true' | 'false';
+    }, cachePolicy?: CachePolicy): Promise<ApiResponse<{
+        categories: Category[];
+    }>>;
     /**
-     * Create new category
+     * Get category by ID (validates it belongs to the site)
      */
-    createCategory(data: CreateCategoryRequest): Promise<ApiResponse<Category>>;
+    getCategoryById(siteName: string, id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<{
+        category: Category;
+    }>>;
     /**
-     * Update category
+     * Get product categories for a site
      */
-    updateCategory(id: number, data: Partial<CreateCategoryRequest>): Promise<ApiResponse<Category>>;
+    getProductCategories(siteName: string, params?: {
+        parent_id?: string;
+        include_subcategories?: 'true' | 'false';
+    }, cachePolicy?: CachePolicy): Promise<ApiResponse<{
+        categories: Category[];
+    }>>;
     /**
-     * Delete category
+     * Create new category for a site
      */
-    deleteCategory(id: number): Promise<ApiResponse<{
+    createCategory(siteName: string, data: CreateCategoryRequest, csrfToken?: string): Promise<ApiResponse<{
         message: string;
+        category_id: number;
     }>>;
     /**
-     * Get category tree (hierarchical structure)
-     */
-    getCategoryTree(rootId?: number): Promise<ApiResponse<Array<Category & {
-        children: Category[];
-    }>>>;
-    /**
-     * Get category children
+     * Create new product category for a site
      */
-    getCategoryChildren(id: number): Promise<ApiResponse<Category[]>>;
-    /**
-     * Get category parent
-     */
-    getCategoryParent(id: number): Promise<ApiResponse<Category | null>>;
-    /**
-     * Move category to new parent
-     */
-    moveCategoryToParent(id: number, parentId: number | null): Promise<ApiResponse<Category>>;
-    /**
-     * Get category breadcrumb path
-     */
-    getCategoryBreadcrumb(id: number): Promise<ApiResponse<Array<{
-        id: number;
-        name: string;
-        slug: string;
-    }>>>;
+    createProductCategory(siteName: string, data: Omit<CreateCategoryRequest, 'category_type'>, csrfToken?: string): Promise<ApiResponse<{
+        message: string;
+        category_id: number;
+    }>>;
     /**
-     * Get category content/products
+     * Update category (validates it belongs to the site)
      */
-    getCategoryContent(id: number, params?: {
-        page?: number;
-        limit?: number;
-        type?: 'content' | 'products' | 'all';
-    }): Promise<ApiResponse<{
-        content: any[];
-        products: any[];
-        total: number;
+    updateCategory(siteName: string, id: number, data: Partial<CreateCategoryRequest>, csrfToken?: string): Promise<ApiResponse<{
+        message: string;
     }>>;
     /**
-     * Bulk update category order
+     * Delete category (validates it belongs to the site)
      */
-    updateCategoryOrder(updates: Array<{
-        id: number;
-        order: number;
-        parentId?: number;
-    }>): Promise<ApiResponse<{
+    deleteCategory(siteName: string, id: number, csrfToken?: string): Promise<ApiResponse<{
         message: string;
     }>>;
     /**
-     * Search categories
+     * Associate pages or products with categories
      */
-    searchCategories(query: string, params?: {
-        limit?: number;
-        organizationId?: number;
-    }): Promise<ApiResponse<Category[]>>;
+    associateCategories(siteName: string, data: {
+        entity_id: number;
+        entity_type: 'page' | 'product';
+        category_ids: number[];
+    }, csrfToken?: string): Promise<ApiResponse<{
+        message: string;
+    }>>;
     private buildCategoryTags;
 }
 

package/dist/index.js

@@ -1589,115 +1589,114 @@ var CategoriesClient = class extends BaseClient {
     super(http, "/api/v1", cache);
   }
   /**
-   * Get all categories
+   * Get all categories for a site
    */
-  async getCategories(params) {
-    return this.getPaginated("/categories", params);
-  }
-  /**
-   * Get category by ID
-   */
-  async getCategoryById(id) {
-    return this.getSingle(`/categories/${id}`);
-  }
-  /**
-   * Get category by slug
-   */
-  async getCategoryBySlug(slug) {
-    return this.getSingle(`/categories/slug/${slug}`);
+  async getCategories(siteName, params, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      params,
+      this.buildCategoryTags(siteName),
+      cachePolicy,
+      () => this.http.get(path, params)
+    );
   }
   /**
-   * Get product category by slug (for products)
+   * Get category by ID (validates it belongs to the site)
    */
-  async getProductCategoryBySlug(siteName, slug, cachePolicy) {
-    const endpoint = this.siteScopedEndpoint(
-      siteName,
-      `/product_category/slug/${encodeURIComponent(slug)}`,
-      { includeSitesSegment: false }
-    );
+  async getCategoryById(siteName, id, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(siteName, `/categories/${id}`, { includeSitesSegment: false });
     const path = this.buildPath(endpoint);
     return this.fetchWithCache(
       endpoint,
       void 0,
-      this.buildCategoryTags(siteName, slug),
+      this.buildCategoryTags(siteName, `categories:id:${id}`),
       cachePolicy,
       () => this.http.get(path)
     );
   }
   /**
-   * Create new category
+   * Get product categories for a site
    */
-  async createCategory(data) {
-    return this.create("/categories", data);
-  }
-  /**
-   * Update category
-   */
-  async updateCategory(id, data) {
-    return this.update(`/categories/${id}`, data);
-  }
-  /**
-   * Delete category
-   */
-  async deleteCategory(id) {
-    return this.delete(`/categories/${id}`);
-  }
-  /**
-   * Get category tree (hierarchical structure)
-   */
-  async getCategoryTree(rootId) {
-    const endpoint = rootId ? `/categories/tree/${rootId}` : "/categories/tree";
-    return this.getSingle(endpoint);
-  }
-  /**
-   * Get category children
-   */
-  async getCategoryChildren(id) {
-    return this.getSingle(`/categories/${id}/children`);
-  }
-  /**
-   * Get category parent
-   */
-  async getCategoryParent(id) {
-    return this.getSingle(`/categories/${id}/parent`);
+  async getProductCategories(siteName, params, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories/product", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      params,
+      this.buildCategoryTags(siteName, "categories:product"),
+      cachePolicy,
+      () => this.http.get(path, params)
+    );
   }
   /**
-   * Move category to new parent
+   * Create new category for a site
    */
-  async moveCategoryToParent(id, parentId) {
-    return this.patch(`/categories/${id}`, { parentId });
+  async createCategory(siteName, data, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.post(path, data, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName) });
+    }
+    return result;
   }
   /**
-   * Get category breadcrumb path
+   * Create new product category for a site
    */
-  async getCategoryBreadcrumb(id) {
-    return this.getSingle(`/categories/${id}/breadcrumb`);
+  async createProductCategory(siteName, data, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories/product", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.post(path, data, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName, "categories:product") });
+    }
+    return result;
   }
   /**
-   * Get category content/products
+   * Update category (validates it belongs to the site)
    */
-  async getCategoryContent(id, params) {
-    return this.http.get(`/categories/${id}/content`, params);
+  async updateCategory(siteName, id, data, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, `/categories/${id}`, { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.put(path, data, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName, `categories:id:${id}`) });
+    }
+    return result;
   }
   /**
-   * Bulk update category order
+   * Delete category (validates it belongs to the site)
    */
-  async updateCategoryOrder(updates) {
-    return this.create("/categories/reorder", { updates });
+  async deleteCategory(siteName, id, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, `/categories/${id}`, { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.delete(path, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName) });
+    }
+    return result;
   }
   /**
-   * Search categories
+   * Associate pages or products with categories
    */
-  async searchCategories(query, params) {
-    return this.http.get(`/categories/search`, { q: query, ...params });
+  async associateCategories(siteName, data, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories/associate", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.post(path, data, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName) });
+    }
+    return result;
   }
-  buildCategoryTags(siteName, slug) {
+  buildCategoryTags(siteName, extraTag) {
     const tags = /* @__PURE__ */ new Set(["categories"]);
     if (siteName) {
       tags.add(`categories:site:${siteName}`);
     }
-    if (slug) {
-      tags.add(`categories:product:${siteName}:${slug}`);
+    if (extraTag) {
+      tags.add(extraTag);
     }
     return Array.from(tags.values());
   }

package/dist/index.mjs

@@ -1527,115 +1527,114 @@ var CategoriesClient = class extends BaseClient {
     super(http, "/api/v1", cache);
   }
   /**
-   * Get all categories
+   * Get all categories for a site
    */
-  async getCategories(params) {
-    return this.getPaginated("/categories", params);
-  }
-  /**
-   * Get category by ID
-   */
-  async getCategoryById(id) {
-    return this.getSingle(`/categories/${id}`);
-  }
-  /**
-   * Get category by slug
-   */
-  async getCategoryBySlug(slug) {
-    return this.getSingle(`/categories/slug/${slug}`);
+  async getCategories(siteName, params, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      params,
+      this.buildCategoryTags(siteName),
+      cachePolicy,
+      () => this.http.get(path, params)
+    );
   }
   /**
-   * Get product category by slug (for products)
+   * Get category by ID (validates it belongs to the site)
    */
-  async getProductCategoryBySlug(siteName, slug, cachePolicy) {
-    const endpoint = this.siteScopedEndpoint(
-      siteName,
-      `/product_category/slug/${encodeURIComponent(slug)}`,
-      { includeSitesSegment: false }
-    );
+  async getCategoryById(siteName, id, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(siteName, `/categories/${id}`, { includeSitesSegment: false });
     const path = this.buildPath(endpoint);
     return this.fetchWithCache(
       endpoint,
       void 0,
-      this.buildCategoryTags(siteName, slug),
+      this.buildCategoryTags(siteName, `categories:id:${id}`),
       cachePolicy,
       () => this.http.get(path)
     );
   }
   /**
-   * Create new category
+   * Get product categories for a site
    */
-  async createCategory(data) {
-    return this.create("/categories", data);
-  }
-  /**
-   * Update category
-   */
-  async updateCategory(id, data) {
-    return this.update(`/categories/${id}`, data);
-  }
-  /**
-   * Delete category
-   */
-  async deleteCategory(id) {
-    return this.delete(`/categories/${id}`);
-  }
-  /**
-   * Get category tree (hierarchical structure)
-   */
-  async getCategoryTree(rootId) {
-    const endpoint = rootId ? `/categories/tree/${rootId}` : "/categories/tree";
-    return this.getSingle(endpoint);
-  }
-  /**
-   * Get category children
-   */
-  async getCategoryChildren(id) {
-    return this.getSingle(`/categories/${id}/children`);
-  }
-  /**
-   * Get category parent
-   */
-  async getCategoryParent(id) {
-    return this.getSingle(`/categories/${id}/parent`);
+  async getProductCategories(siteName, params, cachePolicy) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories/product", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    return this.fetchWithCache(
+      endpoint,
+      params,
+      this.buildCategoryTags(siteName, "categories:product"),
+      cachePolicy,
+      () => this.http.get(path, params)
+    );
   }
   /**
-   * Move category to new parent
+   * Create new category for a site
    */
-  async moveCategoryToParent(id, parentId) {
-    return this.patch(`/categories/${id}`, { parentId });
+  async createCategory(siteName, data, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.post(path, data, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName) });
+    }
+    return result;
   }
   /**
-   * Get category breadcrumb path
+   * Create new product category for a site
    */
-  async getCategoryBreadcrumb(id) {
-    return this.getSingle(`/categories/${id}/breadcrumb`);
+  async createProductCategory(siteName, data, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories/product", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.post(path, data, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName, "categories:product") });
+    }
+    return result;
   }
   /**
-   * Get category content/products
+   * Update category (validates it belongs to the site)
    */
-  async getCategoryContent(id, params) {
-    return this.http.get(`/categories/${id}/content`, params);
+  async updateCategory(siteName, id, data, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, `/categories/${id}`, { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.put(path, data, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName, `categories:id:${id}`) });
+    }
+    return result;
   }
   /**
-   * Bulk update category order
+   * Delete category (validates it belongs to the site)
    */
-  async updateCategoryOrder(updates) {
-    return this.create("/categories/reorder", { updates });
+  async deleteCategory(siteName, id, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, `/categories/${id}`, { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.delete(path, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName) });
+    }
+    return result;
   }
   /**
-   * Search categories
+   * Associate pages or products with categories
    */
-  async searchCategories(query, params) {
-    return this.http.get(`/categories/search`, { q: query, ...params });
+  async associateCategories(siteName, data, csrfToken) {
+    const endpoint = this.siteScopedEndpoint(siteName, "/categories/associate", { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+    const result = await this.http.post(path, data, { csrfToken });
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName) });
+    }
+    return result;
   }
-  buildCategoryTags(siteName, slug) {
+  buildCategoryTags(siteName, extraTag) {
     const tags = /* @__PURE__ */ new Set(["categories"]);
     if (siteName) {
       tags.add(`categories:site:${siteName}`);
     }
-    if (slug) {
-      tags.add(`categories:product:${siteName}:${slug}`);
+    if (extraTag) {
+      tags.add(extraTag);
     }
     return Array.from(tags.values());
   }

package/package.json

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

package/src/client/categories-client.ts

@@ -8,7 +8,6 @@ import type { CachePolicy } from '../cache/types';
 import type {
   Category,
   CreateCategoryRequest,
-  PaginatedResponse,
   ApiResponse,
 } from '../types';
 
@@ -18,161 +17,181 @@ export class CategoriesClient extends BaseClient {
   }
 
   /**
-   * Get all categories
+   * Get all categories for a site
    */
-  async getCategories(params?: { 
-    page?: number; 
-    limit?: number;
-    parentId?: number;
-    organizationId?: number;
-  }): Promise<PaginatedResponse<Category>> {
-    return this.getPaginated<Category>('/categories', params);
-  }
+  async getCategories(
+    siteName: string,
+    params?: {
+      category_type?: 'post' | 'product';
+      parent_id?: string;
+      include_subcategories?: 'true' | 'false';
+    },
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<{ categories: Category[] }>> {
+    const endpoint = this.siteScopedEndpoint(siteName, '/categories', { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
 
-  /**
-   * Get category by ID
-   */
-  async getCategoryById(id: number): Promise<ApiResponse<Category>> {
-    return this.getSingle<Category>(`/categories/${id}`);
+    return this.fetchWithCache<ApiResponse<{ categories: Category[] }>>(
+      endpoint,
+      params,
+      this.buildCategoryTags(siteName),
+      cachePolicy,
+      () => this.http.get<{ categories: Category[] }>(path, params)
+    );
   }
 
   /**
-   * Get category by slug
+   * Get category by ID (validates it belongs to the site)
    */
-  async getCategoryBySlug(slug: string): Promise<ApiResponse<Category>> {
-    return this.getSingle<Category>(`/categories/slug/${slug}`);
+  async getCategoryById(siteName: string, id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<{ category: Category }>> {
+    const endpoint = this.siteScopedEndpoint(siteName, `/categories/${id}`, { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<{ category: Category }>>(
+      endpoint,
+      undefined,
+      this.buildCategoryTags(siteName, `categories:id:${id}`),
+      cachePolicy,
+      () => this.http.get<{ category: Category }>(path)
+    );
   }
 
   /**
-   * Get product category by slug (for products)
+   * Get product categories for a site
    */
-  async getProductCategoryBySlug(
+  async getProductCategories(
     siteName: string,
-    slug: string,
+    params?: {
+      parent_id?: string;
+      include_subcategories?: 'true' | 'false';
+    },
     cachePolicy?: CachePolicy
-  ): Promise<ApiResponse<Category>> {
-    const endpoint = this.siteScopedEndpoint(
-      siteName,
-      `/product_category/slug/${encodeURIComponent(slug)}`,
-      { includeSitesSegment: false }
-    );
+  ): Promise<ApiResponse<{ categories: Category[] }>> {
+    const endpoint = this.siteScopedEndpoint(siteName, '/categories/product', { includeSitesSegment: false });
     const path = this.buildPath(endpoint);
 
-    return this.fetchWithCache<ApiResponse<Category>>(
+    return this.fetchWithCache<ApiResponse<{ categories: Category[] }>>(
       endpoint,
-      undefined,
-      this.buildCategoryTags(siteName, slug),
+      params,
+      this.buildCategoryTags(siteName, 'categories:product'),
       cachePolicy,
-      () => this.http.get<Category>(path)
+      () => this.http.get<{ categories: Category[] }>(path, params)
     );
   }
 
   /**
-   * Create new category
+   * Create new category for a site
    */
-  async createCategory(data: CreateCategoryRequest): Promise<ApiResponse<Category>> {
-    return this.create<CreateCategoryRequest, Category>('/categories', data);
-  }
+  async createCategory(
+    siteName: string,
+    data: CreateCategoryRequest,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ message: string; category_id: number }>> {
+    const endpoint = this.siteScopedEndpoint(siteName, '/categories', { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
 
-  /**
-   * Update category
-   */
-  async updateCategory(id: number, data: Partial<CreateCategoryRequest>): Promise<ApiResponse<Category>> {
-    return this.update<Partial<CreateCategoryRequest>, Category>(`/categories/${id}`, data);
-  }
+    const result = await this.http.post<{ message: string; category_id: number }>(path, data, { csrfToken });
 
-  /**
-   * Delete category
-   */
-  async deleteCategory(id: number): Promise<ApiResponse<{ message: string }>> {
-    return this.delete<{ message: string }>(`/categories/${id}`);
-  }
+    // Invalidate cache after creation
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName) });
+    }
 
-  /**
-   * Get category tree (hierarchical structure)
-   */
-  async getCategoryTree(rootId?: number): Promise<ApiResponse<Array<Category & {
-    children: Category[];
-  }>>> {
-    const endpoint = rootId ? `/categories/tree/${rootId}` : '/categories/tree';
-    return this.getSingle(endpoint);
+    return result;
   }
 
   /**
-   * Get category children
+   * Create new product category for a site
    */
-  async getCategoryChildren(id: number): Promise<ApiResponse<Category[]>> {
-    return this.getSingle<Category[]>(`/categories/${id}/children`);
-  }
+  async createProductCategory(
+    siteName: string,
+    data: Omit<CreateCategoryRequest, 'category_type'>,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ message: string; category_id: number }>> {
+    const endpoint = this.siteScopedEndpoint(siteName, '/categories/product', { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
 
-  /**
-   * Get category parent
-   */
-  async getCategoryParent(id: number): Promise<ApiResponse<Category | null>> {
-    return this.getSingle<Category | null>(`/categories/${id}/parent`);
-  }
+    const result = await this.http.post<{ message: string; category_id: number }>(path, data, { csrfToken });
 
-  /**
-   * Move category to new parent
-   */
-  async moveCategoryToParent(id: number, parentId: number | null): Promise<ApiResponse<Category>> {
-    return this.patch<{ parentId: number | null }, Category>(`/categories/${id}`, { parentId });
-  }
+    // Invalidate cache after creation
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName, 'categories:product') });
+    }
 
-  /**
-   * Get category breadcrumb path
-   */
-  async getCategoryBreadcrumb(id: number): Promise<ApiResponse<Array<{
-    id: number;
-    name: string;
-    slug: string;
-  }>>> {
-    return this.getSingle(`/categories/${id}/breadcrumb`);
+    return result;
   }
 
   /**
-   * Get category content/products
+   * Update category (validates it belongs to the site)
    */
-  async getCategoryContent(id: number, params?: {
-    page?: number;
-    limit?: number;
-    type?: 'content' | 'products' | 'all';
-  }): Promise<ApiResponse<{
-    content: any[];
-    products: any[];
-    total: number;
-  }>> {
-    return this.http.get(`/categories/${id}/content`, params);
+  async updateCategory(
+    siteName: string,
+    id: number,
+    data: Partial<CreateCategoryRequest>,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ message: string }>> {
+    const endpoint = this.siteScopedEndpoint(siteName, `/categories/${id}`, { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+
+    const result = await this.http.put<{ message: string }>(path, data, { csrfToken });
+
+    // Invalidate cache after update
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName, `categories:id:${id}`) });
+    }
+
+    return result;
   }
 
   /**
-   * Bulk update category order
+   * Delete category (validates it belongs to the site)
    */
-  async updateCategoryOrder(updates: Array<{
-    id: number;
-    order: number;
-    parentId?: number;
-  }>): Promise<ApiResponse<{ message: string }>> {
-    return this.create('/categories/reorder', { updates });
+  async deleteCategory(siteName: string, id: number, csrfToken?: string): Promise<ApiResponse<{ message: string }>> {
+    const endpoint = this.siteScopedEndpoint(siteName, `/categories/${id}`, { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+
+    const result = await this.http.delete<{ message: string }>(path, { csrfToken });
+
+    // Invalidate cache after deletion
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName) });
+    }
+
+    return result;
   }
 
   /**
-   * Search categories
+   * Associate pages or products with categories
    */
-  async searchCategories(query: string, params?: {
-    limit?: number;
-    organizationId?: number;
-  }): Promise<ApiResponse<Category[]>> {
-    return this.http.get(`/categories/search`, { q: query, ...params });
+  async associateCategories(
+    siteName: string,
+    data: {
+      entity_id: number;
+      entity_type: 'page' | 'product';
+      category_ids: number[];
+    },
+    csrfToken?: string
+  ): Promise<ApiResponse<{ message: string }>> {
+    const endpoint = this.siteScopedEndpoint(siteName, '/categories/associate', { includeSitesSegment: false });
+    const path = this.buildPath(endpoint);
+
+    const result = await this.http.post<{ message: string }>(path, data, { csrfToken });
+
+    // Invalidate cache after association
+    if (this.cache) {
+      await this.cache.invalidate({ tags: this.buildCategoryTags(siteName) });
+    }
+
+    return result;
   }
 
-  private buildCategoryTags(siteName: string, slug: string): string[] {
+  private buildCategoryTags(siteName: string, extraTag?: string): string[] {
     const tags = new Set<string>(['categories']);
     if (siteName) {
       tags.add(`categories:site:${siteName}`);
     }
-    if (slug) {
-      tags.add(`categories:product:${siteName}:${slug}`);
+    if (extraTag) {
+      tags.add(extraTag);
     }
     return Array.from(tags.values());
   }

package/src/types/index.ts

@@ -638,6 +638,7 @@ export interface SiteUserOrder {
 export interface RequestOtpRequest {
   email: string;
   waitlist?: boolean;  // Mark user as waitlist signup
+  metadata?: Record<string, any>;  // Optional metadata to set on user creation/update
 }
 
 export interface VerifyOtpRequest {