@symbo.ls/sdk 3.1.2 → 3.2.6

package/src/services/ScreenshotService.js

@@ -0,0 +1,258 @@
+import { BaseService } from './BaseService.js'
+
+export class ScreenshotService extends BaseService {
+  constructor (config) {
+    super(config)
+    this._debounceTimers = new Map()
+    this._inflightRefreshes = new Map()
+  }
+
+  // ==================== PROJECT-LEVEL OPERATIONS ====================
+
+  async createScreenshotProject (payload) {
+    this._requireReady('createScreenshotProject')
+    try {
+      const response = await this._request('/screenshots/projects', {
+        method: 'POST',
+        body: JSON.stringify(payload),
+        methodName: 'createScreenshotProject'
+      })
+      if (response.success) {return response}
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to create screenshot project: ${error.message}`, { cause: error })
+    }
+  }
+
+  async getProjectScreenshots (projectKey, params = {}) {
+    this._requireReady('getProjectScreenshots')
+    if (!projectKey) {throw new Error('projectKey is required')}
+    const { type = 'all', status, limit = 50, offset = 0 } = params
+    const qs = new URLSearchParams()
+    if (type) {qs.set('type', type)}
+    if (status) {qs.set('status', status)}
+    if (limit != null) {qs.set('limit', String(limit))}
+    if (offset != null) {qs.set('offset', String(offset))}
+    try {
+      const response = await this._request(
+        `/screenshots/projects/${encodeURIComponent(projectKey)}${qs.toString() ? `?${qs.toString()}` : ''}`,
+        { method: 'GET', methodName: 'getProjectScreenshots' }
+      )
+      if (response.success) {return response}
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to get project screenshots: ${error.message}`, { cause: error })
+    }
+  }
+
+  async reprocessProjectScreenshots (projectKey, body = {}) {
+    this._requireReady('reprocessProjectScreenshots')
+    if (!projectKey) {throw new Error('projectKey is required')}
+    try {
+      const response = await this._request(
+        `/screenshots/projects/${encodeURIComponent(projectKey)}/reprocess`,
+        { method: 'POST', body: JSON.stringify(body), methodName: 'reprocessProjectScreenshots' }
+      )
+      if (response.success) {return response}
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to reprocess screenshots: ${error.message}`, { cause: error })
+    }
+  }
+
+  async recreateProjectScreenshots (projectKey, body = {}) {
+    this._requireReady('recreateProjectScreenshots')
+    if (!projectKey) {throw new Error('projectKey is required')}
+    try {
+      const response = await this._request(
+        `/screenshots/projects/${encodeURIComponent(projectKey)}/recreate`,
+        { method: 'POST', body: JSON.stringify(body), methodName: 'recreateProjectScreenshots' }
+      )
+      if (response.success) {return response}
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to recreate screenshots: ${error.message}`, { cause: error })
+    }
+  }
+
+  async deleteProjectScreenshots (projectKey) {
+    this._requireReady('deleteProjectScreenshots')
+    if (!projectKey) {throw new Error('projectKey is required')}
+    try {
+      const response = await this._request(
+        `/screenshots/projects/${encodeURIComponent(projectKey)}`,
+        { method: 'DELETE', methodName: 'deleteProjectScreenshots' }
+      )
+      if (response.success) {return response}
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to delete project screenshots: ${error.message}`, { cause: error })
+    }
+  }
+
+  // ==================== THUMBNAIL ====================
+
+  async getThumbnailCandidate (projectKey, options = {}) {
+    this._requireReady('getThumbnailCandidate')
+    if (!projectKey) {throw new Error('projectKey is required')}
+    const { includeData = false } = options
+    const qs = new URLSearchParams()
+    if (includeData) {qs.set('include_data', 'true')}
+    try {
+      const response = await this._request(
+        `/screenshots/projects/${encodeURIComponent(projectKey)}/thumbnail/candidate${qs.toString() ? `?${qs.toString()}` : ''}`,
+        { method: 'GET', methodName: 'getThumbnailCandidate' }
+      )
+      if (response.success) {return response}
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to get thumbnail candidate: ${error.message}`, { cause: error })
+    }
+  }
+
+  async updateProjectThumbnail (projectKey, body = {}) {
+    this._requireReady('updateProjectThumbnail')
+    if (!projectKey) {throw new Error('projectKey is required')}
+    try {
+      const response = await this._request(
+        `/screenshots/projects/${encodeURIComponent(projectKey)}/thumbnail`,
+        { method: 'POST', body: JSON.stringify(body), methodName: 'updateProjectThumbnail' }
+      )
+      if (response.success) {return response}
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to update project thumbnail: ${error.message}`, { cause: error })
+    }
+  }
+
+  // ==================== INDIVIDUAL SHOTS ====================
+
+  async getPageScreenshot (screenshotId, format = 'json') {
+    this._requireReady('getPageScreenshot')
+    if (!screenshotId) {throw new Error('screenshotId is required')}
+    const qs = new URLSearchParams()
+    if (format) {qs.set('format', format)}
+    try {
+      return await this._request(
+        `/screenshots/pages/${encodeURIComponent(screenshotId)}${qs.toString() ? `?${qs.toString()}` : ''}`,
+        { method: 'GET', methodName: 'getPageScreenshot' }
+      )
+    } catch (error) {
+      throw new Error(`Failed to get page screenshot: ${error.message}`, { cause: error })
+    }
+  }
+
+  async getComponentScreenshot (screenshotId, format = 'json') {
+    this._requireReady('getComponentScreenshot')
+    if (!screenshotId) {throw new Error('screenshotId is required')}
+    const qs = new URLSearchParams()
+    if (format) {qs.set('format', format)}
+    try {
+      return await this._request(
+        `/screenshots/components/${encodeURIComponent(screenshotId)}${qs.toString() ? `?${qs.toString()}` : ''}`,
+        { method: 'GET', methodName: 'getComponentScreenshot' }
+      )
+    } catch (error) {
+      throw new Error(`Failed to get component screenshot: ${error.message}`, { cause: error })
+    }
+  }
+
+  async getScreenshotByKey (projectKey, type, key, format = 'json') {
+    this._requireReady('getScreenshotByKey')
+    if (!projectKey) {throw new Error('projectKey is required')}
+    if (!type || !['component', 'page'].includes(String(type))) {
+      throw new Error("type must be 'component' or 'page'")
+    }
+    if (!key) {throw new Error('key is required')}
+    const qs = new URLSearchParams()
+    if (format) {qs.set('format', format)}
+    const sub = type === 'component' ? 'components' : 'pages'
+    try {
+      return await this._request(
+        `/screenshots/projects/${encodeURIComponent(projectKey)}/${sub}/${encodeURIComponent(key)}${qs.toString() ? `?${qs.toString()}` : ''}`,
+        { method: 'GET', methodName: 'getScreenshotByKey' }
+      )
+    } catch (error) {
+      throw new Error(`Failed to get screenshot by key: ${error.message}`, { cause: error })
+    }
+  }
+
+  async getQueueStatistics () {
+    this._requireReady('getQueueStatistics')
+    try {
+      const response = await this._request('/screenshots/queue/stats', {
+        method: 'GET',
+        methodName: 'getQueueStatistics'
+      })
+      if (response.success) {return response}
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to get queue statistics: ${error.message}`, { cause: error })
+    }
+  }
+
+  // ==================== COMBINATION/DEBOUNCED ====================
+
+  /**
+   * Debounced thumbnail refresh that recreates screenshots and then updates thumbnail.
+   * Subsequent calls within debounce window reset the timer.
+   */
+  async refreshThumbnail (projectKey, options = {}) {
+    this._requireReady('refreshThumbnail')
+    if (!projectKey) {throw new Error('projectKey is required')}
+
+    const {
+      debounceMs = 15000,
+      waitAfterRecreateMs = 20000,
+      recreate = {
+        process_pages: true,
+        process_components: false,
+        process_descriptions: false,
+        force: false,
+        priority: 5
+      },
+      thumbnail = {
+        strategy: 'auto',
+        force: true
+      }
+    } = options
+
+    // Clear existing debounce timer if present
+    const existingTimer = this._debounceTimers.get(projectKey)
+    if (existingTimer) {
+      clearTimeout(existingTimer)
+    }
+
+    // Wrap execution in a promise we store, so callers can await the outcome
+    const executionPromise = await new Promise(resolve => {
+      const timer = setTimeout(async () => {
+        try {
+          // Step 1: queue screenshot recreation (non-blocking server-side)
+          await this.recreateProjectScreenshots(projectKey, recreate)
+
+          // Step 2: wait for some time to allow processing to progress
+          await new Promise(resolveDelay => { setTimeout(resolveDelay, waitAfterRecreateMs) })
+
+          // Step 3: update thumbnail using best candidate
+          const result = await this.updateProjectThumbnail(projectKey, thumbnail)
+          resolve(result)
+        } catch (e) {
+          // Resolve with error object but do not throw to avoid unhandled rejections
+          resolve({ success: false, error: e?.message || String(e) })
+        } finally {
+          this._debounceTimers.delete(projectKey)
+          this._inflightRefreshes.delete(projectKey)
+        }
+      }, debounceMs)
+
+      this._debounceTimers.set(projectKey, timer)
+    })
+
+    this._inflightRefreshes.set(projectKey, executionPromise)
+    return executionPromise
+  }
+}
+
+export default ScreenshotService
+
+

package/src/services/SubscriptionService.js

@@ -0,0 +1,425 @@
+import { BaseService } from './BaseService.js'
+
+export class SubscriptionService extends BaseService {
+  // ==================== SUBSCRIPTION METHODS ====================
+
+  /**
+   * Create a new subscription checkout session
+   */
+  async createSubscription (subscriptionData) {
+    this._requireReady('createSubscription')
+    if (!subscriptionData || typeof subscriptionData !== 'object') {
+      throw new Error('Subscription data is required')
+    }
+
+    const { projectId, planId, pricingKey = 'monthly', seats = 1, successUrl, cancelUrl } = subscriptionData
+
+    if (!projectId) {
+      throw new Error('Project ID is required')
+    }
+    if (!planId) {
+      throw new Error('Plan ID is required')
+    }
+
+    try {
+      const response = await this._request('/subscriptions', {
+        method: 'POST',
+        body: JSON.stringify({
+          projectId,
+          planId,
+          pricingKey,
+          seats,
+          successUrl,
+          cancelUrl
+        }),
+        methodName: 'createSubscription'
+      })
+      if (response.success) {
+        return response.data
+      }
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to create subscription: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Get subscription status and usage for a project
+   */
+  async getProjectStatus (projectId) {
+    this._requireReady('getProjectStatus')
+    if (!projectId) {
+      throw new Error('Project ID is required')
+    }
+
+    try {
+      const response = await this._request(`/subscriptions/project/${projectId}`, {
+        method: 'GET',
+        methodName: 'getProjectStatus'
+      })
+      if (response.success) {
+        return response.data
+      }
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to get project subscription status: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Get usage data for a subscription
+   */
+  async getUsage (subscriptionId) {
+    this._requireReady('getUsage')
+    if (!subscriptionId) {
+      throw new Error('Subscription ID is required')
+    }
+
+    try {
+      const response = await this._request(`/subscriptions/${subscriptionId}/usage`, {
+        method: 'GET',
+        methodName: 'getUsage'
+      })
+      if (response.success) {
+        return response.data
+      }
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to get subscription usage: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Cancel a subscription
+   */
+  async cancelSubscription (subscriptionId) {
+    this._requireReady('cancelSubscription')
+    if (!subscriptionId) {
+      throw new Error('Subscription ID is required')
+    }
+
+    try {
+      const response = await this._request(`/subscriptions/${subscriptionId}/cancel`, {
+        method: 'POST',
+        methodName: 'cancelSubscription'
+      })
+      if (response.success) {
+        return response.data
+      }
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to cancel subscription: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * List invoices for a subscription
+   */
+  async listInvoices (subscriptionId, options = {}) {
+    this._requireReady('listInvoices')
+    if (!subscriptionId) {
+      throw new Error('Subscription ID is required')
+    }
+
+    const { page = 1, limit = 20, status, startingAfter } = options
+
+    try {
+      const queryParams = new URLSearchParams()
+      if (page) {queryParams.append('page', page.toString())}
+      if (limit) {queryParams.append('limit', limit.toString())}
+      if (status) {queryParams.append('status', status)}
+      if (startingAfter) {queryParams.append('startingAfter', startingAfter)}
+
+      const queryString = queryParams.toString()
+      const url = `/subscriptions/${subscriptionId}/invoices${queryString ? `?${queryString}` : ''}`
+
+      const response = await this._request(url, {
+        method: 'GET',
+        methodName: 'listInvoices'
+      })
+      if (response.success) {
+        return response.data
+      }
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to list invoices: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Get customer portal URL for a subscription
+   */
+  async getPortalUrl (subscriptionId, returnUrl) {
+    this._requireReady('getPortalUrl')
+    if (!subscriptionId) {
+      throw new Error('Subscription ID is required')
+    }
+
+    try {
+      const queryParams = new URLSearchParams()
+      if (returnUrl) {queryParams.append('returnUrl', returnUrl)}
+
+      const queryString = queryParams.toString()
+      const url = `/subscriptions/${subscriptionId}/portal${queryString ? `?${queryString}` : ''}`
+
+      const response = await this._request(url, {
+        method: 'GET',
+        methodName: 'getPortalUrl'
+      })
+      if (response.success) {
+        return response.data
+      }
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to get portal URL: ${error.message}`, { cause: error })
+    }
+  }
+
+  // ==================== SUBSCRIPTION HELPER METHODS ====================
+
+  /**
+   * Helper method to create subscription with validation
+   */
+  async createSubscriptionWithValidation (subscriptionData) {
+    if (!subscriptionData || typeof subscriptionData !== 'object') {
+      throw new Error('Subscription data must be a valid object')
+    }
+
+    // Basic validation for required fields
+    const requiredFields = ['projectId', 'planId']
+    for (const field of requiredFields) {
+      if (!subscriptionData[field]) {
+        throw new Error(`Required field '${field}' is missing`)
+      }
+    }
+
+    // Validate seats is a positive integer
+    if (subscriptionData.seats != null) {
+      if (!Number.isInteger(subscriptionData.seats) || subscriptionData.seats < 1) {
+        throw new Error('Seats must be a positive integer')
+      }
+    }
+
+    // Validate pricingKey
+    if (subscriptionData.pricingKey && !['monthly', 'yearly'].includes(subscriptionData.pricingKey)) {
+      throw new Error('Pricing key must be either "monthly" or "yearly"')
+    }
+
+    return await this.createSubscription(subscriptionData)
+  }
+
+  /**
+   * Helper method to check if project has active subscription
+   */
+  async hasActiveSubscription (projectId) {
+    try {
+      const status = await this.getProjectStatus(projectId)
+      return status.hasSubscription === true
+    } catch (error) {
+      throw new Error(`Failed to check subscription status: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Helper method to get subscription details for a project
+   */
+  async getProjectSubscription (projectId) {
+    try {
+      const status = await this.getProjectStatus(projectId)
+      if (!status.hasSubscription) {
+        return null
+      }
+      return status.subscription
+    } catch (error) {
+      throw new Error(`Failed to get project subscription: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Helper method to get usage with limits for a project
+   */
+  async getProjectUsage (projectId) {
+    try {
+      const status = await this.getProjectStatus(projectId)
+      if (!status.hasSubscription) {
+        return null
+      }
+      return status.usage
+    } catch (error) {
+      throw new Error(`Failed to get project usage: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Helper method to get invoices with pagination
+   */
+  async getInvoicesWithPagination (subscriptionId, options = {}) {
+    try {
+      const result = await this.listInvoices(subscriptionId, options)
+      return {
+        invoices: result.data || [],
+        pagination: result.pagination || {}
+      }
+    } catch (error) {
+      throw new Error(`Failed to get invoices with pagination: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Helper method to check if subscription is active
+   */
+  async isSubscriptionActive (subscriptionId) {
+    try {
+      const usage = await this.getUsage(subscriptionId)
+      // This would depend on the actual response structure
+      // You might need to adjust based on your backend response
+      return usage && usage.subscription && usage.subscription.status === 'active'
+    } catch (error) {
+      throw new Error(`Failed to check subscription status: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Helper method to get subscription limits
+   */
+  async getSubscriptionLimits (subscriptionId) {
+    try {
+      const usage = await this.getUsage(subscriptionId)
+      return usage.limits || {}
+    } catch (error) {
+      throw new Error(`Failed to get subscription limits: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Change subscription (unified endpoint for all pricing changes)
+   */
+  async changeSubscription (changeData) {
+    this._requireReady('changeSubscription')
+    if (!changeData || typeof changeData !== 'object') {
+      throw new Error('Change data is required')
+    }
+
+    const { subscriptionId, planId, pricingKey, seats = 1, projectId, successUrl, cancelUrl } = changeData
+
+    if (!subscriptionId) {
+      throw new Error('Subscription ID is required')
+    }
+    if (!pricingKey) {
+      throw new Error('Pricing key is required')
+    }
+
+    try {
+      const response = await this._request(`/subscriptions/${subscriptionId}/change`, {
+        method: 'POST',
+        body: JSON.stringify({
+          planId,
+          pricingKey,
+          seats,
+          projectId,
+          successUrl,
+          cancelUrl
+        }),
+        methodName: 'changeSubscription'
+      })
+      if (response.success) {
+        return response.data
+      }
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to change subscription: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Downgrade subscription to free plan
+   */
+  async downgrade (downgradeData) {
+    this._requireReady('downgrade')
+    if (!downgradeData || typeof downgradeData !== 'object') {
+      throw new Error('Downgrade data is required')
+    }
+
+    const { subscriptionId, reason } = downgradeData
+
+    if (!subscriptionId) {
+      throw new Error('Subscription ID is required')
+    }
+
+    try {
+      const response = await this._request(`/subscriptions/${subscriptionId}/downgrade`, {
+        method: 'POST',
+        body: JSON.stringify({
+          reason
+        }),
+        methodName: 'downgrade'
+      })
+      if (response.success) {
+        return response.data
+      }
+      throw new Error(response.message)
+    } catch (error) {
+      throw new Error(`Failed to downgrade subscription: ${error.message}`, { cause: error })
+    }
+  }
+
+  /**
+   * Helper method to change subscription with validation
+   */
+  async changeSubscriptionWithValidation (changeData) {
+    if (!changeData || typeof changeData !== 'object') {
+      throw new Error('Change data must be a valid object')
+    }
+
+    // Basic validation for required fields
+    const requiredFields = ['subscriptionId', 'pricingKey']
+    for (const field of requiredFields) {
+      if (!changeData[field]) {
+        throw new Error(`Required field '${field}' is missing`)
+      }
+    }
+
+    // Validate seats is a positive integer if provided
+    if (changeData.seats != null) {
+      if (!Number.isInteger(changeData.seats) || changeData.seats < 1) {
+        throw new Error('Seats must be a positive integer')
+      }
+    }
+
+    // Validate subscriptionId is a string
+    if (typeof changeData.subscriptionId !== 'string') {
+      throw new Error('Subscription ID must be a valid string')
+    }
+
+    // Validate planId is a string if provided
+    if (changeData.planId && typeof changeData.planId !== 'string') {
+      throw new Error('Plan ID must be a valid string')
+    }
+
+    return await this.changeSubscription(changeData)
+  }
+
+  /**
+   * Helper method to downgrade subscription with validation
+   */
+  async downgradeWithValidation (downgradeData) {
+    if (!downgradeData || typeof downgradeData !== 'object') {
+      throw new Error('Downgrade data must be a valid object')
+    }
+
+    // Validate subscriptionId is required and is a string
+    if (!downgradeData.subscriptionId) {
+      throw new Error('Subscription ID is required')
+    }
+    if (typeof downgradeData.subscriptionId !== 'string') {
+      throw new Error('Subscription ID must be a valid string')
+    }
+
+    // Validate reason is a string if provided
+    if (downgradeData.reason && typeof downgradeData.reason !== 'string') {
+      throw new Error('Reason must be a valid string')
+    }
+
+    return await this.downgrade(downgradeData)
+  }
+}