perspectapi-ts-sdk 2.6.0 → 2.8.1

package/README.md

@@ -147,7 +147,7 @@ export default {
 };
 ```
 
-When PerspectAPI sends a webhook—or when your Worker mutates data directly—call `perspect.cache.invalidate({ tags: [...] })` using the tags emitted by the SDK (`products:site:<site>`, `content:slug:<site>:<slug>`, etc.) so stale entries are purged immediately.
+When PerspectAPI sends a webhook—or when your Worker mutates data directly—call `perspect.cache.invalidate({ tags: [...] })` using the tags emitted by the SDK (`products:site:<site>`, `content:slug:<site>:<slug>`, `content:category:<site>:<category_slug>`, etc.) so stale entries are purged immediately.
 
 ### Webhook-driven cache invalidation
 
@@ -200,6 +200,8 @@ const tagMap: Record<string, (e: WebhookEvent) => string[]> = {
     `categories`,
     `categories:site:${event.site}`,
     `categories:product:${event.site}:${event.slug}`,
+    `products:category:${event.site}:${event.slug}`,
+    `content:category:${event.site}:${event.slug}`,
   ],
 };
 
@@ -392,6 +394,17 @@ const post = await client.content.getContentById(123);
 // Get content by slug
 const page = await client.content.getContentBySlug('your-site-name', 'about-us');
 
+// Get content by category slug
+const categoryContent = await client.content.getContentByCategorySlug(
+  'your-site-name',
+  'news',
+  {
+    page: 1,
+    limit: 20,
+    page_type: 'post'
+  }
+);
+
 // Create new content
 const newPost = await client.content.createContent({
   page_title: 'My New Post',

package/dist/index.d.mts

@@ -265,7 +265,7 @@ interface NewsletterUnsubscribeResponse {
     status?: string;
 }
 type ContentStatus = 'draft' | 'publish' | 'private' | 'trash';
-type ContentType = 'post' | 'page';
+type ContentType = 'post' | 'page' | 'block';
 interface Content {
     id: number;
     pageTitle: string;
@@ -312,6 +312,22 @@ interface Category {
     createdAt: string;
     updatedAt: string;
 }
+interface CategorySummary {
+    id: number;
+    name: string;
+    slug: string;
+    description?: string;
+}
+interface ContentCategoryResponse {
+    category: CategorySummary;
+    items: Content[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        pages: number;
+    };
+}
 interface CreateCategoryRequest {
     name: string;
     slug?: string;
@@ -557,6 +573,83 @@ interface ContactStatusResponse {
     processed_at?: string;
     metadata?: Record<string, any>;
 }
+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;
+    created_at: string;
+    last_login_at?: string;
+}
+interface SiteUserProfile {
+    [key: string]: {
+        value: any;
+        updated_at: string;
+    };
+}
+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;
+}
+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;
+}
+interface RequestOtpRequest {
+    email: string;
+    waitlist?: boolean;
+}
+interface VerifyOtpRequest {
+    email: string;
+    code: string;
+}
+interface VerifyOtpResponse {
+    success: boolean;
+    token: string;
+    user: {
+        id: string;
+        email: string;
+        first_name?: string;
+        last_name?: string;
+        avatar_url?: string;
+    };
+}
+interface UpdateSiteUserRequest {
+    first_name?: string;
+    last_name?: string;
+    avatar_url?: string;
+}
+interface SetProfileValueRequest {
+    value: string;
+}
 interface ApiError {
     message: string;
     code?: string;
@@ -781,6 +874,10 @@ declare class ContentClient extends BaseClient {
      * Get content by ID
      */
     getContentById(id: number, cachePolicy?: CachePolicy): Promise<ApiResponse<Content>>;
+    /**
+     * Get content by category slug for a site
+     */
+    getContentByCategorySlug(siteName: string, categorySlug: string, params?: ContentQueryParams, cachePolicy?: CachePolicy): Promise<ApiResponse<ContentCategoryResponse>>;
     /**
      * Get content by slug for a site
      */
@@ -1236,6 +1333,72 @@ declare class ProductsClient extends BaseClient {
      * e.g., 'shop/shoes/nike-air' -> 'shop', 'product-name' -> undefined
      */
     private extractSlugPrefix;
+    /**
+     * Get all options (and their values) for a product
+     */
+    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;
+        }>;
+    }>>>;
+    /**
+     * Create a new product option (e.g., "Size", "Color")
+     */
+    createProductOption(siteName: string, productId: number, data: {
+        option_name: string;
+        display_order?: number;
+    }): Promise<ApiResponse<{
+        option_id: number;
+        option_name: string;
+        display_order: number;
+    }>>;
+    /**
+     * Create a new value for a product option (e.g., "Small", "Red")
+     */
+    createProductOptionValue(siteName: string, productId: number, optionId: number, data: {
+        value: string;
+        display_order?: number;
+    }): Promise<ApiResponse<{
+        value_id: number;
+        value: string;
+        display_order: number;
+    }>>;
+    /**
+     * Get all SKUs for a product (with their option value combinations)
+     */
+    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;
+    }>>>;
+    /**
+     * Create or update a SKU for a product variant combination
+     */
+    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;
+    }>>;
 }
 
 /**
@@ -2029,6 +2192,210 @@ declare class NewsletterClient extends BaseClient {
     static getTrackingPixel(): Uint8Array;
 }
 
+/**
+ * Site Users client for PerspectAPI SDK
+ * Handles per-site customer accounts (OTP-based auth, profiles, orders, subscriptions)
+ */
+
+declare class SiteUsersClient extends BaseClient {
+    constructor(http: any, cache?: CacheManager);
+    /**
+     * Build a site user endpoint scoped to a site (without /sites prefix)
+     */
+    private siteUserEndpoint;
+    /**
+     * Request OTP for login/signup
+     * @param siteName - The site name
+     * @param data - Email address
+     * @param csrfToken - CSRF token (required for browser-based submissions)
+     */
+    requestOtp(siteName: string, data: RequestOtpRequest, csrfToken?: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * 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)
+     */
+    verifyOtp(siteName: string, data: VerifyOtpRequest, csrfToken?: string): Promise<ApiResponse<VerifyOtpResponse>>;
+    /**
+     * 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)
+     */
+    verifyOtpAndSetAuth(siteName: string, data: VerifyOtpRequest, csrfToken?: string): Promise<ApiResponse<VerifyOtpResponse>>;
+    /**
+     * Logout (clear session cookie)
+     * @param siteName - The site name
+     */
+    logout(siteName: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * Get current user profile
+     * @param siteName - The site name
+     */
+    getMe(siteName: string): Promise<ApiResponse<{
+        user: SiteUser;
+        profile: SiteUserProfile;
+    }>>;
+    /**
+     * Update current user profile
+     * @param siteName - The site name
+     * @param data - Fields to update
+     * @param csrfToken - CSRF token (required)
+     */
+    updateMe(siteName: string, data: UpdateSiteUserRequest, csrfToken?: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * Get all profile key-values
+     * @param siteName - The site name
+     */
+    getProfile(siteName: string): Promise<ApiResponse<{
+        profile: SiteUserProfile;
+    }>>;
+    /**
+     * 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)
+     */
+    setProfileValue(siteName: string, key: string, value: string, csrfToken?: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * Delete a profile key-value
+     * @param siteName - The site name
+     * @param key - Profile key to delete
+     * @param csrfToken - CSRF token (required)
+     */
+    deleteProfileValue(siteName: string, key: string, csrfToken?: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /**
+     * Get transaction/order history
+     * @param siteName - The site name
+     * @param params - Pagination params
+     */
+    getOrders(siteName: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        orders: SiteUserOrder[];
+    }>>;
+    /**
+     * Get single order detail
+     * @param siteName - The site name
+     * @param orderId - Order ID or session ID
+     */
+    getOrder(siteName: string, orderId: string): Promise<ApiResponse<{
+        order: any;
+    }>>;
+    /**
+     * Get payment subscriptions
+     * @param siteName - The site name
+     * @param params - Pagination params
+     */
+    getSubscriptions(siteName: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        subscriptions: SiteUserSubscription[];
+    }>>;
+    /**
+     * Get single subscription detail
+     * @param siteName - The site name
+     * @param id - Subscription ID
+     */
+    getSubscription(siteName: string, id: string): Promise<ApiResponse<{
+        subscription: SiteUserSubscription;
+    }>>;
+    /**
+     * Cancel a subscription (marks for cancellation at period end)
+     * @param siteName - The site name
+     * @param id - Subscription ID
+     * @param csrfToken - CSRF token (required)
+     */
+    cancelSubscription(siteName: string, id: string, csrfToken?: string): Promise<ApiResponse<{
+        success: boolean;
+        message: string;
+    }>>;
+    /**
+     * Get linked newsletter subscriptions
+     * @param siteName - The site name
+     */
+    getNewsletterSubscriptions(siteName: string): Promise<ApiResponse<{
+        newsletters: any[];
+    }>>;
+    /**
+     * List all site users (admin only)
+     * @param siteName - The site name
+     * @param params - Query params (limit, offset, status)
+     */
+    listUsers(siteName: string, params?: {
+        limit?: number;
+        offset?: number;
+        status?: string;
+    }): Promise<ApiResponse<{
+        users: SiteUser[];
+    }>>;
+    /**
+     * Get user detail (admin only)
+     * @param siteName - The site name
+     * @param userId - User ID
+     */
+    getUser(siteName: string, userId: string): Promise<ApiResponse<{
+        user: SiteUser;
+        profile: SiteUserProfile;
+    }>>;
+    /**
+     * Update user status (admin only)
+     * @param siteName - The site name
+     * @param userId - User ID
+     * @param status - New status
+     * @param csrfToken - CSRF token (required)
+     */
+    updateUserStatus(siteName: string, userId: string, status: 'active' | 'suspended' | 'pending_verification', csrfToken?: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+}
+
 /**
  * Main PerspectAPI SDK Client
  * Cloudflare Workers compatible TypeScript SDK
@@ -2048,6 +2415,7 @@ declare class PerspectApiClient {
     readonly checkout: CheckoutClient;
     readonly contact: ContactClient;
     readonly newsletter: NewsletterClient;
+    readonly siteUsers: SiteUsersClient;
     constructor(config: PerspectApiConfig);
     /**
      * Update authentication token
@@ -2452,4 +2820,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, type CategorySummary, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, type ContentCategoryResponse, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type RequestOtpRequest, type ResponsiveImageSizes, type SetProfileValueRequest, type SignInRequest, type SignUpRequest, type Site, type SiteUser, type SiteUserOrder, type SiteUserProfile, type SiteUserSubscription, SiteUsersClient, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type UpdateSiteUserRequest, type User, type VerifyOtpRequest, type VerifyOtpResponse, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };