perspectapi-ts-sdk 2.7.0 → 2.8.2

package/src/client/site-users-client.ts

@@ -0,0 +1,352 @@
+/**
+ * Site Users client for PerspectAPI SDK
+ * Handles per-site customer accounts (OTP-based auth, profiles, orders, subscriptions)
+ */
+
+import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
+import type {
+  SiteUser,
+  SiteUserProfile,
+  SiteUserSubscription,
+  SiteUserOrder,
+  RequestOtpRequest,
+  VerifyOtpRequest,
+  VerifyOtpResponse,
+  UpdateSiteUserRequest,
+  SetProfileValueRequest,
+  ApiResponse,
+} from '../types';
+
+export class SiteUsersClient extends BaseClient {
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
+  }
+
+  /**
+   * Build a site user endpoint scoped to a site (without /sites prefix)
+   */
+  private siteUserEndpoint(siteName: string, endpoint: string): string {
+    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: string,
+    data: RequestOtpRequest,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    if (typeof window !== 'undefined' && !csrfToken) {
+      console.warn('CSRF token recommended for browser-based OTP requests');
+    }
+
+    return this.create<RequestOtpRequest, { success: boolean }>(
+      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: string,
+    data: VerifyOtpRequest,
+    csrfToken?: string
+  ): Promise<ApiResponse<VerifyOtpResponse>> {
+    if (typeof window !== 'undefined' && !csrfToken) {
+      console.warn('CSRF token recommended for browser-based OTP verification');
+    }
+
+    return this.create<VerifyOtpRequest, VerifyOtpResponse>(
+      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: string,
+    data: VerifyOtpRequest,
+    csrfToken?: string
+  ): Promise<ApiResponse<VerifyOtpResponse>> {
+    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: string): Promise<ApiResponse<{ success: boolean }>> {
+    return this.create<Record<string, never>, { success: boolean }>(
+      this.siteUserEndpoint(siteName, '/users/logout'),
+      {}
+    );
+  }
+
+  // ============================================================================
+  // AUTHENTICATED ENDPOINTS (site user JWT required)
+  // ============================================================================
+
+  /**
+   * Get current user profile
+   * @param siteName - The site name
+   */
+  async getMe(siteName: string): Promise<ApiResponse<{ user: SiteUser; profile: SiteUserProfile }>> {
+    return this.getSingle<{ user: SiteUser; profile: SiteUserProfile }>(
+      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: string,
+    data: UpdateSiteUserRequest,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    return this.patch<UpdateSiteUserRequest, { success: boolean }>(
+      this.siteUserEndpoint(siteName, '/users/me'),
+      data,
+      csrfToken
+    );
+  }
+
+  /**
+   * Get all profile key-values
+   * @param siteName - The site name
+   */
+  async getProfile(siteName: string): Promise<ApiResponse<{ profile: SiteUserProfile }>> {
+    return this.getSingle<{ profile: SiteUserProfile }>(
+      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: string,
+    key: string,
+    value: string,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    return this.update<SetProfileValueRequest, { success: boolean }>(
+      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: string,
+    key: string,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    return this.delete<{ success: boolean }>(
+      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: string,
+    params?: { limit?: number; offset?: number }
+  ): Promise<ApiResponse<{ orders: SiteUserOrder[] }>> {
+    return this.http.get<{ orders: SiteUserOrder[] }>(
+      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: string, orderId: string): Promise<ApiResponse<{ order: any }>> {
+    return this.getSingle<{ order: any }>(
+      this.siteUserEndpoint(siteName, `/users/me/orders/${encodeURIComponent(orderId)}`)
+    );
+  }
+
+  /**
+   * Get payment subscriptions
+   * @param siteName - The site name
+   * @param params - Pagination params
+   */
+  async getSubscriptions(
+    siteName: string,
+    params?: { limit?: number; offset?: number }
+  ): Promise<ApiResponse<{ subscriptions: SiteUserSubscription[] }>> {
+    return this.http.get<{ subscriptions: SiteUserSubscription[] }>(
+      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: string, id: string): Promise<ApiResponse<{ subscription: SiteUserSubscription }>> {
+    return this.getSingle<{ subscription: SiteUserSubscription }>(
+      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: string,
+    id: string,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ success: boolean; message: string }>> {
+    return this.create<Record<string, never>, { success: boolean; message: string }>(
+      this.siteUserEndpoint(siteName, `/users/me/subscriptions/${encodeURIComponent(id)}/cancel`),
+      {},
+      csrfToken
+    );
+  }
+
+  /**
+   * Get linked newsletter subscriptions
+   * @param siteName - The site name
+   */
+  async getNewsletterSubscriptions(siteName: string): Promise<ApiResponse<{ newsletters: any[] }>> {
+    return this.getSingle<{ newsletters: any[] }>(
+      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: string,
+    params?: { limit?: number; offset?: number; status?: string }
+  ): Promise<ApiResponse<{ users: SiteUser[] }>> {
+    return this.http.get<{ users: SiteUser[] }>(
+      this.buildPath(this.siteUserEndpoint(siteName, '/users')),
+      params
+    );
+  }
+
+  /**
+   * Get user detail (admin only)
+   * @param siteName - The site name
+   * @param userId - User ID
+   */
+  async getUser(siteName: string, userId: string): Promise<ApiResponse<{ user: SiteUser; profile: SiteUserProfile }>> {
+    return this.getSingle<{ user: SiteUser; profile: SiteUserProfile }>(
+      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: string,
+    userId: string,
+    status: 'active' | 'suspended' | 'pending_verification',
+    csrfToken?: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    return this.patch<{ status: string }, { success: boolean }>(
+      this.siteUserEndpoint(siteName, `/users/${encodeURIComponent(userId)}/status`),
+      { status },
+      csrfToken
+    );
+  }
+}

package/src/index.ts

@@ -19,6 +19,7 @@ export { WebhooksClient } from './client/webhooks-client';
 export { CheckoutClient } from './client/checkout-client';
 export { ContactClient } from './client/contact-client';
 export { NewsletterClient } from './client/newsletter-client';
+export { SiteUsersClient } from './client/site-users-client';
 
 // Base classes
 export { BaseClient } from './client/base-client';
@@ -106,4 +107,13 @@ export type {
   NewsletterUnsubscribeResponse,
   ContactSubmitResponse,
   ContactStatusResponse,
+  SiteUser,
+  SiteUserProfile,
+  SiteUserSubscription,
+  SiteUserOrder,
+  RequestOtpRequest,
+  VerifyOtpRequest,
+  VerifyOtpResponse,
+  UpdateSiteUserRequest,
+  SetProfileValueRequest,
 } from './types';

package/src/perspect-api-client.ts

@@ -16,6 +16,7 @@ import { WebhooksClient } from './client/webhooks-client';
 import { CheckoutClient } from './client/checkout-client';
 import { ContactClient } from './client/contact-client';
 import { NewsletterClient } from './client/newsletter-client';
+import { SiteUsersClient } from './client/site-users-client';
 
 import type { PerspectApiConfig, ApiResponse } from './types';
 
@@ -35,6 +36,7 @@ export class PerspectApiClient {
   public readonly checkout: CheckoutClient;
   public readonly contact: ContactClient;
   public readonly newsletter: NewsletterClient;
+  public readonly siteUsers: SiteUsersClient;
 
   constructor(config: PerspectApiConfig) {
     // Validate required configuration
@@ -58,6 +60,7 @@ export class PerspectApiClient {
     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);
   }
 
   /**

package/src/types/index.ts

@@ -214,7 +214,7 @@ export interface NewsletterUnsubscribeResponse {
 
 // Content Management
 export type ContentStatus = 'draft' | 'publish' | 'private' | 'trash';
-export type ContentType = 'post' | 'page';
+export type ContentType = 'post' | 'page' | 'block';
 
 export interface Content {
   id: number;
@@ -579,6 +579,95 @@ export interface ContactStatusResponse {
   metadata?: Record<string, any>;
 }
 
+// Site Users (customer accounts)
+export interface SiteUser {
+  id: string;
+  email: string;
+  first_name?: string;
+  last_name?: string;
+  avatar_url?: string;
+  status: 'active' | 'suspended' | 'pending_verification';
+  email_verified: boolean;
+  waitlist: boolean;
+  metadata?: Record<string, any>;
+  created_at: string;
+  last_login_at?: string;
+}
+
+export interface SiteUserProfile {
+  [key: string]: {
+    value: any;
+    updated_at: string;
+  };
+}
+
+export interface SiteUserSubscription {
+  id: string;
+  provider: string;
+  provider_subscription_id?: string;
+  plan_name?: string;
+  plan_id?: string;
+  status: 'active' | 'past_due' | 'canceled' | 'paused' | 'trialing' | 'expired';
+  amount?: number;
+  currency?: string;
+  billing_interval?: string;
+  billing_interval_count?: number;
+  current_period_start?: string;
+  current_period_end?: string;
+  trial_start?: string;
+  trial_end?: string;
+  canceled_at?: string;
+  cancel_at_period_end: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface SiteUserOrder {
+  session_id: string;
+  order_id?: string;
+  customer_email?: string;
+  amount_total: number;
+  currency: string;
+  status: string;
+  payment_status?: string;
+  line_items: any[];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface RequestOtpRequest {
+  email: string;
+  waitlist?: boolean;  // Mark user as waitlist signup
+}
+
+export interface VerifyOtpRequest {
+  email: string;
+  code: string;
+}
+
+export interface VerifyOtpResponse {
+  success: boolean;
+  token: string;  // JWT token for cross-domain authentication
+  user: {
+    id: string;
+    email: string;
+    first_name?: string;
+    last_name?: string;
+    avatar_url?: string;
+  };
+}
+
+export interface UpdateSiteUserRequest {
+  first_name?: string;
+  last_name?: string;
+  avatar_url?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface SetProfileValueRequest {
+  value: string;
+}
+
 // Error Types
 export interface ApiError {
   message: string;

package/src/utils/validators.ts

@@ -1,7 +1,7 @@
 import type { ContentType } from '../types';
 
 export const MAX_API_QUERY_LIMIT = 100;
-const ALLOWED_CONTENT_TYPES: ReadonlyArray<ContentType> = ['post', 'page'];
+const ALLOWED_CONTENT_TYPES: ReadonlyArray<ContentType> = ['post', 'page', 'block'];
 
 export function validateLimit(limit: number, context: string): number {
   if (typeof limit !== 'number' || Number.isNaN(limit) || !Number.isFinite(limit)) {
@@ -50,4 +50,3 @@ export function validateOptionalContentType(
     )}.`,
   );
 }
-