perspectapi-ts-sdk 3.0.2 → 3.2.0

package/src/client/bundles-client.ts

@@ -0,0 +1,263 @@
+/**
+ * Bundles & Collections client for PerspectAPI SDK
+ */
+
+import { BaseClient } from './base-client';
+import type { CacheManager } from '../cache/cache-manager';
+import type { CachePolicy } from '../cache/types';
+import type {
+  ProductBundleGroup,
+  CreateBundleGroupRequest,
+  BundleCollection,
+  CreateBundleCollectionRequest,
+  BundleCollectionItem,
+  BundleCollectionItemWithProduct,
+  AddCollectionItemRequest,
+  ApiResponse,
+} from '../types';
+
+export class BundlesClient extends BaseClient {
+  constructor(http: any, cache?: CacheManager) {
+    super(http, '/api/v1', cache);
+  }
+
+  // ============================================================================
+  // BUNDLE GROUPS (structural "pick N items" on a product)
+  // ============================================================================
+
+  async getBundleGroups(
+    siteName: string,
+    productId: number,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<ProductBundleGroup[]>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/bundle-groups`,
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<ProductBundleGroup[]>>(
+      endpoint,
+      undefined,
+      this.buildBundleTags(siteName, [`bundles:product:${productId}`]),
+      cachePolicy,
+      () => this.http.get<ProductBundleGroup[]>(path)
+    );
+  }
+
+  async createBundleGroup(
+    siteName: string,
+    productId: number,
+    data: CreateBundleGroupRequest
+  ): Promise<ApiResponse<ProductBundleGroup>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/bundle-groups`,
+      { includeSitesSegment: false }
+    );
+    return this.create(endpoint, data);
+  }
+
+  async updateBundleGroup(
+    siteName: string,
+    productId: number,
+    bundleGroupId: number,
+    data: Partial<CreateBundleGroupRequest>
+  ): Promise<ApiResponse<ProductBundleGroup>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/bundle-groups/${bundleGroupId}`,
+      { includeSitesSegment: false }
+    );
+    return this.patch(endpoint, data);
+  }
+
+  async deleteBundleGroup(
+    siteName: string,
+    productId: number,
+    bundleGroupId: number
+  ): Promise<ApiResponse<{ message: string }>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/products/${productId}/bundle-groups/${bundleGroupId}`,
+      { includeSitesSegment: false }
+    );
+    return this.delete<{ message: string }>(endpoint);
+  }
+
+  // ============================================================================
+  // BUNDLE COLLECTIONS (time-bounded, site-scoped sets of products)
+  // ============================================================================
+
+  async getCollections(
+    siteName: string,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<BundleCollection[]>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      '/collections',
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<BundleCollection[]>>(
+      endpoint,
+      undefined,
+      this.buildCollectionTags(siteName, ['collections:list']),
+      cachePolicy,
+      () => this.http.get<BundleCollection[]>(path)
+    );
+  }
+
+  async getCurrentCollection(
+    siteName: string,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<BundleCollection & { items: BundleCollectionItemWithProduct[] }>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      '/collections/current',
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<BundleCollection & { items: BundleCollectionItemWithProduct[] }>>(
+      endpoint,
+      undefined,
+      this.buildCollectionTags(siteName, ['collections:current']),
+      cachePolicy,
+      () => this.http.get(path)
+    );
+  }
+
+  async getCollection(
+    siteName: string,
+    collectionId: number,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<BundleCollection & { items: BundleCollectionItemWithProduct[] }>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/collections/${collectionId}`,
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<BundleCollection & { items: BundleCollectionItemWithProduct[] }>>(
+      endpoint,
+      undefined,
+      this.buildCollectionTags(siteName, [`collections:id:${collectionId}`]),
+      cachePolicy,
+      () => this.http.get(path)
+    );
+  }
+
+  async createCollection(
+    siteName: string,
+    data: CreateBundleCollectionRequest
+  ): Promise<ApiResponse<BundleCollection>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      '/collections',
+      { includeSitesSegment: false }
+    );
+    return this.create(endpoint, data);
+  }
+
+  async updateCollection(
+    siteName: string,
+    collectionId: number,
+    data: Partial<CreateBundleCollectionRequest>
+  ): Promise<ApiResponse<BundleCollection>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/collections/${collectionId}`,
+      { includeSitesSegment: false }
+    );
+    return this.patch(endpoint, data);
+  }
+
+  async deleteCollection(
+    siteName: string,
+    collectionId: number
+  ): Promise<ApiResponse<{ message: string }>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/collections/${collectionId}`,
+      { includeSitesSegment: false }
+    );
+    return this.delete<{ message: string }>(endpoint);
+  }
+
+  // ============================================================================
+  // COLLECTION ITEMS
+  // ============================================================================
+
+  async getCollectionItems(
+    siteName: string,
+    collectionId: number,
+    cachePolicy?: CachePolicy
+  ): Promise<ApiResponse<BundleCollectionItemWithProduct[]>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/collections/${collectionId}/items`,
+      { includeSitesSegment: false }
+    );
+    const path = this.buildPath(endpoint);
+
+    return this.fetchWithCache<ApiResponse<BundleCollectionItemWithProduct[]>>(
+      endpoint,
+      undefined,
+      this.buildCollectionTags(siteName, [`collections:items:${collectionId}`]),
+      cachePolicy,
+      () => this.http.get(path)
+    );
+  }
+
+  async addCollectionItem(
+    siteName: string,
+    collectionId: number,
+    data: AddCollectionItemRequest
+  ): Promise<ApiResponse<BundleCollectionItem>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/collections/${collectionId}/items`,
+      { includeSitesSegment: false }
+    );
+    return this.create(endpoint, data);
+  }
+
+  async removeCollectionItem(
+    siteName: string,
+    collectionId: number,
+    itemId: number
+  ): Promise<ApiResponse<{ message: string }>> {
+    const endpoint = this.siteScopedEndpoint(
+      siteName,
+      `/collections/${collectionId}/items/${itemId}`,
+      { includeSitesSegment: false }
+    );
+    return this.delete<{ message: string }>(endpoint);
+  }
+
+  // ============================================================================
+  // CACHE TAGS
+  // ============================================================================
+
+  private buildBundleTags(siteName?: string, extraTags: string[] = []): string[] {
+    const tags = new Set<string>(['bundles']);
+    if (siteName) {
+      tags.add(`bundles:site:${siteName}`);
+    }
+    extraTags.filter(Boolean).forEach(tag => tags.add(tag));
+    return Array.from(tags.values());
+  }
+
+  private buildCollectionTags(siteName?: string, extraTags: string[] = []): string[] {
+    const tags = new Set<string>(['collections']);
+    if (siteName) {
+      tags.add(`collections:site:${siteName}`);
+    }
+    extraTags.filter(Boolean).forEach(tag => tags.add(tag));
+    return Array.from(tags.values());
+  }
+}

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

@@ -10,6 +10,9 @@ import type {
   SiteUserProfile,
   SiteUserSubscription,
   SiteUserOrder,
+  CreditBalance,
+  CreditBalanceWithTransactions,
+  GrantCreditRequest,
   RequestOtpRequest,
   VerifyOtpRequest,
   VerifyOtpResponse,
@@ -290,6 +293,68 @@ export class SiteUsersClient extends BaseClient {
     );
   }
 
+  /**
+   * Pause a subscription via Stripe pause_collection
+   * @param siteName - The site name
+   * @param subscriptionId - Subscription ID
+   * @param csrfToken - CSRF token (required)
+   * @param resumesAt - Optional ISO date string when subscription should auto-resume
+   */
+  async pauseSubscription(
+    siteName: string,
+    subscriptionId: string,
+    csrfToken?: string,
+    resumesAt?: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    const body: Record<string, string> = {};
+    if (resumesAt) {
+      body.resumes_at = resumesAt;
+    }
+    return this.create<Record<string, string>, { success: boolean }>(
+      this.siteUserEndpoint(siteName, `/users/me/subscriptions/${encodeURIComponent(subscriptionId)}/pause`),
+      body,
+      csrfToken
+    );
+  }
+
+  /**
+   * Resume a paused subscription
+   * @param siteName - The site name
+   * @param subscriptionId - Subscription ID
+   * @param csrfToken - CSRF token (required)
+   */
+  async resumeSubscription(
+    siteName: string,
+    subscriptionId: string,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    return this.create<Record<string, never>, { success: boolean }>(
+      this.siteUserEndpoint(siteName, `/users/me/subscriptions/${encodeURIComponent(subscriptionId)}/resume`),
+      {},
+      csrfToken
+    );
+  }
+
+  /**
+   * Change subscription plan tier
+   * @param siteName - The site name
+   * @param subscriptionId - Subscription ID
+   * @param productId - New product ID to switch to
+   * @param csrfToken - CSRF token (required)
+   */
+  async changeSubscriptionPlan(
+    siteName: string,
+    subscriptionId: string,
+    productId: number,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ success: boolean }>> {
+    return this.create<{ product_id: number }, { success: boolean }>(
+      this.siteUserEndpoint(siteName, `/users/me/subscriptions/${encodeURIComponent(subscriptionId)}/change-plan`),
+      { product_id: productId },
+      csrfToken
+    );
+  }
+
   /**
    * Get linked newsletter subscriptions
    * @param siteName - The site name
@@ -300,6 +365,35 @@ export class SiteUsersClient extends BaseClient {
     );
   }
 
+  // ============================================================================
+  // CREDIT ENDPOINTS (site user JWT required)
+  // ============================================================================
+
+  /**
+   * Get current credit balance
+   * @param siteName - The site name
+   */
+  async getCreditBalance(siteName: string): Promise<ApiResponse<CreditBalance>> {
+    return this.getSingle<CreditBalance>(
+      this.siteUserEndpoint(siteName, '/users/me/credits/balance')
+    );
+  }
+
+  /**
+   * Get credit balance and paginated transactions
+   * @param siteName - The site name
+   * @param params - Pagination params
+   */
+  async getCreditTransactions(
+    siteName: string,
+    params?: { limit?: number; offset?: number }
+  ): Promise<ApiResponse<CreditBalanceWithTransactions>> {
+    return this.http.get<CreditBalanceWithTransactions>(
+      this.buildPath(this.siteUserEndpoint(siteName, '/users/me/credits')),
+      params
+    );
+  }
+
   // ============================================================================
   // ADMIN ENDPOINTS (API key auth required)
   // ============================================================================
@@ -349,4 +443,25 @@ export class SiteUsersClient extends BaseClient {
       csrfToken
     );
   }
+
+  /**
+   * Grant credit to a user (admin only)
+   * Adds credit to the user's ledger and Stripe Customer Balance.
+   * @param siteName - The site name
+   * @param userId - User ID
+   * @param data - Amount in cents and description
+   * @param csrfToken - CSRF token (required)
+   */
+  async grantCredit(
+    siteName: string,
+    userId: string,
+    data: GrantCreditRequest,
+    csrfToken?: string
+  ): Promise<ApiResponse<{ success: boolean; new_balance_cents: number }>> {
+    return this.create<GrantCreditRequest, { success: boolean; new_balance_cents: number }>(
+      this.siteUserEndpoint(siteName, `/users/${encodeURIComponent(userId)}/credits/grant`),
+      data,
+      csrfToken
+    );
+  }
 }

package/src/index.ts

@@ -20,6 +20,7 @@ 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';
+export { BundlesClient } from './client/bundles-client';
 
 // Base classes
 export { BaseClient } from './client/base-client';
@@ -116,4 +117,11 @@ export type {
   VerifyOtpResponse,
   UpdateSiteUserRequest,
   SetProfileValueRequest,
+  ProductBundleGroup,
+  CreateBundleGroupRequest,
+  BundleCollection,
+  CreateBundleCollectionRequest,
+  BundleCollectionItem,
+  BundleCollectionItemWithProduct,
+  AddCollectionItemRequest,
 } from './types';

package/src/perspect-api-client.ts

@@ -17,6 +17,7 @@ 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 { BundlesClient } from './client/bundles-client';
 
 import type { PerspectApiConfig, ApiResponse } from './types';
 
@@ -37,6 +38,7 @@ export class PerspectApiClient {
   public readonly contact: ContactClient;
   public readonly newsletter: NewsletterClient;
   public readonly siteUsers: SiteUsersClient;
+  public readonly bundles: BundlesClient;
 
   constructor(config: PerspectApiConfig) {
     // Validate required configuration
@@ -61,6 +63,7 @@ export class PerspectApiClient {
     this.contact = new ContactClient(this.http, this.cache);
     this.newsletter = new NewsletterClient(this.http, this.cache);
     this.siteUsers = new SiteUsersClient(this.http, this.cache);
+    this.bundles = new BundlesClient(this.http, this.cache);
   }
 
   /**

package/src/types/index.ts

@@ -464,6 +464,8 @@ export interface CreateCheckoutSessionRequest {
     quantity: number;
     // SKU-based checkout (variant products)
     sku_id?: number;
+    // Product ID-based checkout (server resolves to Stripe price)
+    product_id?: number;
     // Or define price data inline
     price_data?: {
       currency: string;
@@ -484,6 +486,8 @@ export interface CreateCheckoutSessionRequest {
   customer_email?: string;
   customerEmail?: string;  // Alternative naming
   site_user_id?: string;   // Authenticated site user — enables checkout prefill
+  referral_code?: string;  // Referral code for first-checkout discount
+  referrer_site_user_id?: string;  // Referrer's site_user_id for credit
   currency?: string;
   metadata?: CheckoutMetadata;
   mode?: 'payment' | 'subscription' | 'setup';
@@ -620,6 +624,29 @@ export interface SiteUserOrder {
   completed_at?: string;
 }
 
+// Credits
+export interface CreditTransaction {
+  id: number;
+  amount_cents: number;
+  balance_after_cents: number;
+  type: string;
+  description: string | null;
+  created_at: string;
+}
+
+export interface CreditBalance {
+  balance_cents: number;
+}
+
+export interface CreditBalanceWithTransactions extends CreditBalance {
+  transactions: CreditTransaction[];
+}
+
+export interface GrantCreditRequest {
+  amount_cents: number;
+  description: string;
+}
+
 export interface RequestOtpRequest {
   email: string;
   waitlist?: boolean;  // Mark user as waitlist signup
@@ -654,6 +681,71 @@ export interface SetProfileValueRequest {
   value: string;
 }
 
+// Bundle Groups (structural "pick N items" metadata on a product)
+export interface ProductBundleGroup {
+  bundle_group_id: number;
+  product_id: number;
+  name: string;
+  description?: string;
+  quantity: number;
+  position: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateBundleGroupRequest {
+  name: string;
+  description?: string;
+  quantity: number;
+  position?: number;
+}
+
+// Bundle Collections (time-bounded, site-scoped sets of products)
+export interface BundleCollection {
+  collection_id: number;
+  site_id: string;
+  site_name: string;
+  name: string;
+  description?: string;
+  available_from?: string;
+  available_until?: string;
+  published: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateBundleCollectionRequest {
+  name: string;
+  description?: string;
+  available_from?: string;
+  available_until?: string;
+  published?: number;
+}
+
+export interface BundleCollectionItem {
+  id: number;
+  collection_id: number;
+  product_id: number;
+  max_quantity?: number;
+  position: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface BundleCollectionItemWithProduct extends BundleCollectionItem {
+  product_name: string;
+  slug: string;
+  unit_amount: number;
+  currency: string;
+  image_url?: string;
+}
+
+export interface AddCollectionItemRequest {
+  product_id: number;
+  max_quantity?: number;
+  position?: number;
+}
+
 // Error Types
 export interface ApiError {
   message: string;