perspectapi-ts-sdk 2.8.3 → 3.0.1

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

@@ -29,25 +29,7 @@ export interface PaginatedResponse<T> extends ApiResponse<T[]> {
   };
 }
 
-// Authentication
-export interface SignUpRequest {
-  email: string;
-  password: string;
-  firstName?: string;
-  lastName?: string;
-}
-
-export interface SignInRequest {
-  email: string;
-  password: string;
-}
-
-export interface AuthResponse {
-  message: string;
-  user?: User;
-  token?: string;
-}
-
+// Authentication (OTP-based)
 export interface User {
   id: string;
   email: string;
@@ -480,6 +462,8 @@ export interface CreateCheckoutSessionRequest {
     // Either use existing Stripe price ID
     price?: string;
     quantity: number;
+    // SKU-based checkout (variant products)
+    sku_id?: number;
     // Or define price data inline
     price_data?: {
       currency: string;
@@ -499,6 +483,7 @@ export interface CreateCheckoutSessionRequest {
   cancelUrl?: string;   // Alternative naming
   customer_email?: string;
   customerEmail?: string;  // Alternative naming
+  site_user_id?: string;   // Authenticated site user — enables checkout prefill
   currency?: string;
   metadata?: CheckoutMetadata;
   mode?: 'payment' | 'subscription' | 'setup';