@symbo.ls/sdk 3.2.3 → 3.2.6

package/dist/node/services/ScreenshotService.js

@@ -0,0 +1,285 @@
+import { BaseService } from "./BaseService.js";
+class ScreenshotService extends BaseService {
+  constructor(config) {
+    super(config);
+    this._debounceTimers = /* @__PURE__ */ new Map();
+    this._inflightRefreshes = /* @__PURE__ */ 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 = 15e3,
+      waitAfterRecreateMs = 2e4,
+      recreate = {
+        process_pages: true,
+        process_components: false,
+        process_descriptions: false,
+        force: false,
+        priority: 5
+      },
+      thumbnail = {
+        strategy: "auto",
+        force: true
+      }
+    } = options;
+    const existingTimer = this._debounceTimers.get(projectKey);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+    const executionPromise = await new Promise((resolve) => {
+      const timer = setTimeout(async () => {
+        try {
+          await this.recreateProjectScreenshots(projectKey, recreate);
+          await new Promise((resolveDelay) => {
+            setTimeout(resolveDelay, waitAfterRecreateMs);
+          });
+          const result = await this.updateProjectThumbnail(projectKey, thumbnail);
+          resolve(result);
+        } catch (e) {
+          resolve({ success: false, error: (e == null ? void 0 : 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;
+  }
+}
+var ScreenshotService_default = ScreenshotService;
+export {
+  ScreenshotService,
+  ScreenshotService_default as default
+};

package/dist/node/services/SubscriptionService.js

@@ -0,0 +1,377 @@
+import { BaseService } from "./BaseService.js";
+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");
+    }
+    const requiredFields = ["projectId", "planId"];
+    for (const field of requiredFields) {
+      if (!subscriptionData[field]) {
+        throw new Error(`Required field '${field}' is missing`);
+      }
+    }
+    if (subscriptionData.seats != null) {
+      if (!Number.isInteger(subscriptionData.seats) || subscriptionData.seats < 1) {
+        throw new Error("Seats must be a positive integer");
+      }
+    }
+    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);
+      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");
+    }
+    const requiredFields = ["subscriptionId", "pricingKey"];
+    for (const field of requiredFields) {
+      if (!changeData[field]) {
+        throw new Error(`Required field '${field}' is missing`);
+      }
+    }
+    if (changeData.seats != null) {
+      if (!Number.isInteger(changeData.seats) || changeData.seats < 1) {
+        throw new Error("Seats must be a positive integer");
+      }
+    }
+    if (typeof changeData.subscriptionId !== "string") {
+      throw new Error("Subscription ID must be a valid string");
+    }
+    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");
+    }
+    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");
+    }
+    if (downgradeData.reason && typeof downgradeData.reason !== "string") {
+      throw new Error("Reason must be a valid string");
+    }
+    return await this.downgrade(downgradeData);
+  }
+}
+export {
+  SubscriptionService
+};