perspectapi-ts-sdk 2.6.0 → 2.8.1

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   OrganizationsClient: () => OrganizationsClient,
   PerspectApiClient: () => PerspectApiClient,
   ProductsClient: () => ProductsClient,
+  SiteUsersClient: () => SiteUsersClient,
   SitesClient: () => SitesClient,
   WebhooksClient: () => WebhooksClient,
   buildImageUrl: () => buildImageUrl,
@@ -768,7 +769,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.`);
@@ -902,6 +903,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 +1022,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 +1036,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());
   }
   /**
@@ -1474,6 +1523,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
@@ -2188,6 +2295,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;
@@ -2204,6 +2576,7 @@ var PerspectApiClient = class {
   checkout;
   contact;
   newsletter;
+  siteUsers;
   constructor(config) {
     if (!config.baseUrl) {
       throw new Error("baseUrl is required in PerspectApiConfig");
@@ -2221,6 +2594,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
@@ -2910,6 +3284,7 @@ async function createCheckoutSession(options) {
   OrganizationsClient,
   PerspectApiClient,
   ProductsClient,
+  SiteUsersClient,
   SitesClient,
   WebhooksClient,
   buildImageUrl,