perspectapi-ts-sdk 2.6.0 → 2.8.1

package/dist/index.mjs

@@ -707,7 +707,7 @@ var AuthClient = class extends BaseClient {
 
 // src/utils/validators.ts
 var MAX_API_QUERY_LIMIT = 100;
-var ALLOWED_CONTENT_TYPES = ["post", "page"];
+var ALLOWED_CONTENT_TYPES = ["post", "page", "block"];
 function validateLimit(limit, context) {
   if (typeof limit !== "number" || Number.isNaN(limit) || !Number.isFinite(limit)) {
     throw new Error(`[PerspectAPI] ${context} limit must be a finite number.`);
@@ -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());
   }
   /**
@@ -1413,6 +1461,64 @@ var ProductsClient = class extends BaseClient {
     }
     return void 0;
   }
+  // ============================================================================
+  // PRODUCT OPTIONS AND SKUS (for variants)
+  // ============================================================================
+  /**
+   * Get all options (and their values) for a product
+   */
+  async getProductOptions(siteName, productId) {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/options`,
+      { includeSitesSegment: false }
+    );
+    return this.getSingle(endpoint);
+  }
+  /**
+   * Create a new product option (e.g., "Size", "Color")
+   */
+  async createProductOption(siteName, productId, data) {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/options`,
+      { includeSitesSegment: false }
+    );
+    return this.create(endpoint, data);
+  }
+  /**
+   * Create a new value for a product option (e.g., "Small", "Red")
+   */
+  async createProductOptionValue(siteName, productId, optionId, data) {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/options/${optionId}/values`,
+      { includeSitesSegment: false }
+    );
+    return this.create(endpoint, data);
+  }
+  /**
+   * Get all SKUs for a product (with their option value combinations)
+   */
+  async getProductSkus(siteName, productId) {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/skus`,
+      { includeSitesSegment: false }
+    );
+    return this.getSingle(endpoint);
+  }
+  /**
+   * Create or update a SKU for a product variant combination
+   */
+  async createProductSku(siteName, productId, data) {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/skus`,
+      { includeSitesSegment: false }
+    );
+    return this.create(endpoint, data);
+  }
 };
 
 // src/client/categories-client.ts
@@ -2127,6 +2233,271 @@ var NewsletterClient = class extends BaseClient {
   }
 };
 
+// src/client/site-users-client.ts
+var SiteUsersClient = class extends BaseClient {
+  constructor(http, cache) {
+    super(http, "/api/v1", cache);
+  }
+  /**
+   * Build a site user endpoint scoped to a site (without /sites prefix)
+   */
+  siteUserEndpoint(siteName, endpoint) {
+    return this.siteScopedEndpoint(siteName, endpoint, { includeSitesSegment: false });
+  }
+  // ============================================================================
+  // PUBLIC ENDPOINTS (OTP authentication)
+  // ============================================================================
+  /**
+   * Request OTP for login/signup
+   * @param siteName - The site name
+   * @param data - Email address
+   * @param csrfToken - CSRF token (required for browser-based submissions)
+   */
+  async requestOtp(siteName, data, csrfToken) {
+    if (typeof window !== "undefined" && !csrfToken) {
+      console.warn("CSRF token recommended for browser-based OTP requests");
+    }
+    return this.create(
+      this.siteUserEndpoint(siteName, "/users/request-otp"),
+      data,
+      csrfToken
+    );
+  }
+  /**
+   * Verify OTP and get JWT token
+   *
+   * For cross-domain authentication, you must manually set the token after verification:
+   * ```typescript
+   * const response = await client.siteUsers.verifyOtp('mysite', { email, code });
+   * const { token, user } = response.data;
+   *
+   * // Store token securely (choose one):
+   * // Option 1: Memory (lost on refresh, most secure)
+   * client.setAuth(token);
+   *
+   * // Option 2: httpOnly cookie on YOUR domain (recommended for production)
+   * await fetch('/your-api/set-auth-cookie', {
+   *   method: 'POST',
+   *   body: JSON.stringify({ token })
+   * });
+   * client.setAuth(token);
+   *
+   * // Option 3: localStorage (vulnerable to XSS, not recommended)
+   * localStorage.setItem('site_user_token', token);
+   * client.setAuth(token);
+   * ```
+   *
+   * For convenience, use `verifyOtpAndSetAuth()` to automatically set the token in memory.
+   *
+   * @param siteName - The site name
+   * @param data - Email and code
+   * @param csrfToken - CSRF token (required for browser-based submissions)
+   */
+  async verifyOtp(siteName, data, csrfToken) {
+    if (typeof window !== "undefined" && !csrfToken) {
+      console.warn("CSRF token recommended for browser-based OTP verification");
+    }
+    return this.create(
+      this.siteUserEndpoint(siteName, "/users/verify-otp"),
+      data,
+      csrfToken
+    );
+  }
+  /**
+   * Verify OTP and automatically set the token for subsequent requests
+   *
+   * Convenience method that:
+   * 1. Verifies the OTP
+   * 2. Automatically calls setAuth() with the returned token
+   *
+   * Note: Token is stored in memory only and will be lost on page refresh.
+   * For persistent auth, use verifyOtp() and store the token yourself.
+   *
+   * @param siteName - The site name
+   * @param data - Email and code
+   * @param csrfToken - CSRF token (required for browser-based submissions)
+   */
+  async verifyOtpAndSetAuth(siteName, data, csrfToken) {
+    const response = await this.verifyOtp(siteName, data, csrfToken);
+    if (response.data?.token) {
+      this.http.setAuth(response.data.token);
+    }
+    return response;
+  }
+  /**
+   * Logout (clear session cookie)
+   * @param siteName - The site name
+   */
+  async logout(siteName) {
+    return this.create(
+      this.siteUserEndpoint(siteName, "/users/logout"),
+      {}
+    );
+  }
+  // ============================================================================
+  // AUTHENTICATED ENDPOINTS (site user JWT required)
+  // ============================================================================
+  /**
+   * Get current user profile
+   * @param siteName - The site name
+   */
+  async getMe(siteName) {
+    return this.getSingle(
+      this.siteUserEndpoint(siteName, "/users/me")
+    );
+  }
+  /**
+   * Update current user profile
+   * @param siteName - The site name
+   * @param data - Fields to update
+   * @param csrfToken - CSRF token (required)
+   */
+  async updateMe(siteName, data, csrfToken) {
+    return this.patch(
+      this.siteUserEndpoint(siteName, "/users/me"),
+      data,
+      csrfToken
+    );
+  }
+  /**
+   * Get all profile key-values
+   * @param siteName - The site name
+   */
+  async getProfile(siteName) {
+    return this.getSingle(
+      this.siteUserEndpoint(siteName, "/users/me/profile")
+    );
+  }
+  /**
+   * Set a profile key-value
+   * @param siteName - The site name
+   * @param key - Profile key (e.g., 'phone', 'whatsapp', 'address_shipping')
+   * @param value - Profile value (string or JSON string)
+   * @param csrfToken - CSRF token (required)
+   */
+  async setProfileValue(siteName, key, value, csrfToken) {
+    return this.update(
+      this.siteUserEndpoint(siteName, `/users/me/profile/${encodeURIComponent(key)}`),
+      { value },
+      csrfToken
+    );
+  }
+  /**
+   * Delete a profile key-value
+   * @param siteName - The site name
+   * @param key - Profile key to delete
+   * @param csrfToken - CSRF token (required)
+   */
+  async deleteProfileValue(siteName, key, csrfToken) {
+    return this.delete(
+      this.siteUserEndpoint(siteName, `/users/me/profile/${encodeURIComponent(key)}`),
+      csrfToken
+    );
+  }
+  /**
+   * Get transaction/order history
+   * @param siteName - The site name
+   * @param params - Pagination params
+   */
+  async getOrders(siteName, params) {
+    return this.http.get(
+      this.buildPath(this.siteUserEndpoint(siteName, "/users/me/orders")),
+      params
+    );
+  }
+  /**
+   * Get single order detail
+   * @param siteName - The site name
+   * @param orderId - Order ID or session ID
+   */
+  async getOrder(siteName, orderId) {
+    return this.getSingle(
+      this.siteUserEndpoint(siteName, `/users/me/orders/${encodeURIComponent(orderId)}`)
+    );
+  }
+  /**
+   * Get payment subscriptions
+   * @param siteName - The site name
+   * @param params - Pagination params
+   */
+  async getSubscriptions(siteName, params) {
+    return this.http.get(
+      this.buildPath(this.siteUserEndpoint(siteName, "/users/me/subscriptions")),
+      params
+    );
+  }
+  /**
+   * Get single subscription detail
+   * @param siteName - The site name
+   * @param id - Subscription ID
+   */
+  async getSubscription(siteName, id) {
+    return this.getSingle(
+      this.siteUserEndpoint(siteName, `/users/me/subscriptions/${encodeURIComponent(id)}`)
+    );
+  }
+  /**
+   * Cancel a subscription (marks for cancellation at period end)
+   * @param siteName - The site name
+   * @param id - Subscription ID
+   * @param csrfToken - CSRF token (required)
+   */
+  async cancelSubscription(siteName, id, csrfToken) {
+    return this.create(
+      this.siteUserEndpoint(siteName, `/users/me/subscriptions/${encodeURIComponent(id)}/cancel`),
+      {},
+      csrfToken
+    );
+  }
+  /**
+   * Get linked newsletter subscriptions
+   * @param siteName - The site name
+   */
+  async getNewsletterSubscriptions(siteName) {
+    return this.getSingle(
+      this.siteUserEndpoint(siteName, "/users/me/newsletters")
+    );
+  }
+  // ============================================================================
+  // ADMIN ENDPOINTS (API key auth required)
+  // ============================================================================
+  /**
+   * List all site users (admin only)
+   * @param siteName - The site name
+   * @param params - Query params (limit, offset, status)
+   */
+  async listUsers(siteName, params) {
+    return this.http.get(
+      this.buildPath(this.siteUserEndpoint(siteName, "/users")),
+      params
+    );
+  }
+  /**
+   * Get user detail (admin only)
+   * @param siteName - The site name
+   * @param userId - User ID
+   */
+  async getUser(siteName, userId) {
+    return this.getSingle(
+      this.siteUserEndpoint(siteName, `/users/${encodeURIComponent(userId)}`)
+    );
+  }
+  /**
+   * Update user status (admin only)
+   * @param siteName - The site name
+   * @param userId - User ID
+   * @param status - New status
+   * @param csrfToken - CSRF token (required)
+   */
+  async updateUserStatus(siteName, userId, status, csrfToken) {
+    return this.patch(
+      this.siteUserEndpoint(siteName, `/users/${encodeURIComponent(userId)}/status`),
+      { status },
+      csrfToken
+    );
+  }
+};
+
 // src/perspect-api-client.ts
 var PerspectApiClient = class {
   http;
@@ -2143,6 +2514,7 @@ var PerspectApiClient = class {
   checkout;
   contact;
   newsletter;
+  siteUsers;
   constructor(config) {
     if (!config.baseUrl) {
       throw new Error("baseUrl is required in PerspectApiConfig");
@@ -2160,6 +2532,7 @@ var PerspectApiClient = class {
     this.checkout = new CheckoutClient(this.http, this.cache);
     this.contact = new ContactClient(this.http, this.cache);
     this.newsletter = new NewsletterClient(this.http, this.cache);
+    this.siteUsers = new SiteUsersClient(this.http, this.cache);
   }
   /**
    * Update authentication token
@@ -2848,6 +3221,7 @@ export {
   OrganizationsClient,
   PerspectApiClient,
   ProductsClient,
+  SiteUsersClient,
   SitesClient,
   WebhooksClient,
   buildImageUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "2.6.0",
+  "version": "2.8.1",
   "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/client/products-client.ts

@@ -371,4 +371,127 @@ export class ProductsClient extends BaseClient {
     }
     return undefined;
   }
+
+  // ============================================================================
+  // PRODUCT OPTIONS AND SKUS (for variants)
+  // ============================================================================
+
+  /**
+   * Get all options (and their values) for a product
+   */
+  async getProductOptions(
+    siteName: string,
+    productId: number
+  ): Promise<ApiResponse<Array<{
+    option_id: number;
+    option_name: string;
+    display_order: number;
+    values: Array<{
+      value_id: number;
+      value: string;
+      display_order: number;
+    }>;
+  }>>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/options`,
+      { includeSitesSegment: false }
+    );
+    return this.getSingle(endpoint);
+  }
+
+  /**
+   * Create a new product option (e.g., "Size", "Color")
+   */
+  async createProductOption(
+    siteName: string,
+    productId: number,
+    data: { option_name: string; display_order?: number }
+  ): Promise<ApiResponse<{
+    option_id: number;
+    option_name: string;
+    display_order: number;
+  }>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/options`,
+      { includeSitesSegment: false }
+    );
+    return this.create(endpoint, data);
+  }
+
+  /**
+   * Create a new value for a product option (e.g., "Small", "Red")
+   */
+  async createProductOptionValue(
+    siteName: string,
+    productId: number,
+    optionId: number,
+    data: { value: string; display_order?: number }
+  ): Promise<ApiResponse<{
+    value_id: number;
+    value: string;
+    display_order: number;
+  }>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/options/${optionId}/values`,
+      { includeSitesSegment: false }
+    );
+    return this.create(endpoint, data);
+  }
+
+  /**
+   * Get all SKUs for a product (with their option value combinations)
+   */
+  async getProductSkus(
+    siteName: string,
+    productId: number
+  ): Promise<ApiResponse<Array<{
+    sku_id: number;
+    sku: string;
+    price?: number;
+    sale_price?: number;
+    stock_quantity?: number;
+    combination_key: string;
+    value_ids: number[];
+    created_at: string;
+    updated_at: string;
+  }>>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/skus`,
+      { includeSitesSegment: false }
+    );
+    return this.getSingle(endpoint);
+  }
+
+  /**
+   * Create or update a SKU for a product variant combination
+   */
+  async createProductSku(
+    siteName: string,
+    productId: number,
+    data: {
+      sku: string;
+      price?: number | null;
+      sale_price?: number | null;
+      stock_quantity?: number | null;
+      value_ids: number[];
+    }
+  ): Promise<ApiResponse<{
+    sku_id: number;
+    sku: string;
+    price?: number;
+    sale_price?: number;
+    stock_quantity?: number;
+    combination_key: string;
+  }>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/skus`,
+      { includeSitesSegment: false }
+    );
+    return this.create(endpoint, data);
+  }
 }