aiox-core 5.0.0 → 5.0.2

package/pro/license/errors.js

@@ -0,0 +1,450 @@
+/**
+ * License Errors Module
+ *
+ * Custom error classes for license and feature gating.
+ *
+ * @module pro/license/errors
+ * @see ADR-PRO-003 - Feature Gating & Licensing
+ * @see Story PRO-6 - License Key & Feature Gating System
+ */
+
+'use strict';
+
+/**
+ * Error thrown when a pro feature is accessed without a valid license.
+ *
+ * Provides a user-friendly message with activation instructions.
+ * Never exposes sensitive information (license keys, internal state).
+ *
+ * Usage:
+ *   throw new ProFeatureError('pro.squads.premium', 'Premium Squads');
+ *
+ * Message format (per ADR-PRO-003):
+ *   {Feature Name} requires an active AIOS Pro license.
+ *   Your data and configurations are preserved.
+ *   Activate: aios pro activate --key <KEY>
+ *   Purchase: https://synkra.ai/pro
+ */
+class ProFeatureError extends Error {
+  /**
+   * Create a ProFeatureError.
+   *
+   * @param {string} featureId - The feature ID that was requested (e.g., "pro.squads.premium")
+   * @param {string} [friendlyName] - Human-friendly name for the feature
+   * @param {object} [options] - Additional options
+   * @param {string} [options.purchaseUrl] - Custom purchase URL
+   * @param {string} [options.activateCommand] - Custom activation command
+   */
+  constructor(featureId, friendlyName, options = {}) {
+    const name = friendlyName || featureId;
+    const purchaseUrl = options.purchaseUrl || 'https://synkra.ai/pro';
+    const activateCommand = options.activateCommand || 'aios pro activate --key <KEY>';
+
+    const message = [
+      `${name} requires an active AIOS Pro license.`,
+      'Your data and configurations are preserved.',
+      `Activate: ${activateCommand}`,
+      `Purchase: ${purchaseUrl}`,
+    ].join('\n');
+
+    super(message);
+
+    this.name = 'ProFeatureError';
+    this.featureId = featureId;
+    this.friendlyName = name;
+    this.purchaseUrl = purchaseUrl;
+    this.activateCommand = activateCommand;
+
+    // Capture stack trace (V8 engines)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ProFeatureError);
+    }
+  }
+
+  /**
+   * Get formatted message for CLI display.
+   *
+   * @returns {string} Formatted error message
+   */
+  toCliMessage() {
+    return [
+      '',
+      `  ${this.friendlyName} requires an active AIOS Pro license.`,
+      '',
+      '  Your data and configurations are preserved.',
+      '',
+      `  Activate: ${this.activateCommand}`,
+      `  Purchase: ${this.purchaseUrl}`,
+      '',
+    ].join('\n');
+  }
+
+  /**
+   * Get JSON representation for API responses.
+   *
+   * @returns {object} JSON-serializable error object
+   */
+  toJSON() {
+    return {
+      error: 'ProFeatureError',
+      featureId: this.featureId,
+      friendlyName: this.friendlyName,
+      message: `${this.friendlyName} requires an active AIOS Pro license.`,
+      activateCommand: this.activateCommand,
+      purchaseUrl: this.purchaseUrl,
+    };
+  }
+}
+
+/**
+ * Error thrown when license activation fails.
+ */
+class LicenseActivationError extends Error {
+  /**
+   * Create a LicenseActivationError.
+   *
+   * @param {string} message - Error message
+   * @param {string} [code] - Error code (e.g., 'INVALID_KEY', 'NETWORK_ERROR')
+   * @param {object} [details] - Additional error details
+   */
+  constructor(message, code, details = {}) {
+    super(message);
+
+    this.name = 'LicenseActivationError';
+    this.code = code || 'ACTIVATION_FAILED';
+    this.details = details;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, LicenseActivationError);
+    }
+  }
+
+  /**
+   * Create error for invalid key format.
+   *
+   * @returns {LicenseActivationError}
+   */
+  static invalidKeyFormat() {
+    return new LicenseActivationError(
+      'Invalid license key format. Expected: PRO-XXXX-XXXX-XXXX-XXXX',
+      'INVALID_KEY_FORMAT',
+    );
+  }
+
+  /**
+   * Create error for network failure.
+   *
+   * @param {Error} [cause] - Original error
+   * @returns {LicenseActivationError}
+   */
+  static networkError(cause) {
+    return new LicenseActivationError(
+      'Unable to reach license server. Please check your internet connection.',
+      'NETWORK_ERROR',
+      { cause: cause ? cause.message : undefined },
+    );
+  }
+
+  /**
+   * Create error for invalid key (server rejected).
+   *
+   * @returns {LicenseActivationError}
+   */
+  static invalidKey() {
+    return new LicenseActivationError(
+      'The license key is invalid or has been revoked.',
+      'INVALID_KEY',
+    );
+  }
+
+  /**
+   * Create error for expired key.
+   *
+   * @returns {LicenseActivationError}
+   */
+  static expiredKey() {
+    return new LicenseActivationError(
+      'The license key has expired. Please renew at https://synkra.ai/pro',
+      'EXPIRED_KEY',
+    );
+  }
+
+  /**
+   * Create error for seat limit exceeded.
+   *
+   * @param {number} used - Seats currently used
+   * @param {number} max - Maximum seats allowed
+   * @returns {LicenseActivationError}
+   */
+  static seatLimitExceeded(used, max) {
+    return new LicenseActivationError(
+      `Seat limit exceeded. ${used}/${max} seats in use. Deactivate another device or upgrade your license.`,
+      'SEAT_LIMIT_EXCEEDED',
+      { used, max },
+    );
+  }
+
+  /**
+   * Create error for rate limiting.
+   *
+   * @param {number} [retryAfter] - Seconds until retry is allowed
+   * @returns {LicenseActivationError}
+   */
+  static rateLimited(retryAfter) {
+    const message = retryAfter
+      ? `Too many requests. Please try again in ${retryAfter} seconds.`
+      : 'Too many requests. Please try again later.';
+
+    return new LicenseActivationError(message, 'RATE_LIMITED', { retryAfter });
+  }
+
+  /**
+   * Create error for server error.
+   *
+   * @returns {LicenseActivationError}
+   */
+  static serverError() {
+    return new LicenseActivationError(
+      'License server error. Please try again later.',
+      'SERVER_ERROR',
+    );
+  }
+
+  /**
+   * Get JSON representation for API responses.
+   *
+   * @returns {object} JSON-serializable error object
+   */
+  toJSON() {
+    return {
+      error: 'LicenseActivationError',
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+
+/**
+ * Error thrown when license validation fails.
+ */
+class LicenseValidationError extends Error {
+  /**
+   * Create a LicenseValidationError.
+   *
+   * @param {string} message - Error message
+   * @param {string} [code] - Error code
+   */
+  constructor(message, code) {
+    super(message);
+
+    this.name = 'LicenseValidationError';
+    this.code = code || 'VALIDATION_FAILED';
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, LicenseValidationError);
+    }
+  }
+
+  /**
+   * Create error for corrupted cache.
+   *
+   * @returns {LicenseValidationError}
+   */
+  static corruptedCache() {
+    return new LicenseValidationError(
+      'License cache is corrupted. Please reactivate with: aios pro activate --key <KEY>',
+      'CORRUPTED_CACHE',
+    );
+  }
+
+  /**
+   * Create error for machine mismatch.
+   *
+   * @returns {LicenseValidationError}
+   */
+  static machineMismatch() {
+    return new LicenseValidationError(
+      'License was activated on a different machine. Please reactivate.',
+      'MACHINE_MISMATCH',
+    );
+  }
+}
+
+/**
+ * Error thrown when authentication fails.
+ *
+ * Covers signup, login, email verification, and session errors.
+ *
+ * @see Story PRO-11 - Email Authentication & Buyer-Based Pro Activation
+ */
+class AuthError extends Error {
+  /**
+   * Create an AuthError.
+   *
+   * @param {string} message - Error message
+   * @param {string} [code] - Error code (e.g., 'EMAIL_NOT_VERIFIED', 'INVALID_CREDENTIALS')
+   * @param {object} [details] - Additional error details
+   */
+  constructor(message, code, details = {}) {
+    super(message);
+
+    this.name = 'AuthError';
+    this.code = code || 'AUTH_FAILED';
+    this.details = details;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AuthError);
+    }
+  }
+
+  /**
+   * Create error for invalid credentials (wrong email/password).
+   *
+   * @returns {AuthError}
+   */
+  static invalidCredentials() {
+    return new AuthError(
+      'Invalid email or password.',
+      'INVALID_CREDENTIALS',
+    );
+  }
+
+  /**
+   * Create error for email not verified.
+   *
+   * @returns {AuthError}
+   */
+  static emailNotVerified() {
+    return new AuthError(
+      'Please verify your email first. Check your inbox.',
+      'EMAIL_NOT_VERIFIED',
+    );
+  }
+
+  /**
+   * Create error for email already registered.
+   *
+   * @returns {AuthError}
+   */
+  static emailAlreadyRegistered() {
+    return new AuthError(
+      'An account with this email already exists. Try logging in instead.',
+      'EMAIL_ALREADY_REGISTERED',
+    );
+  }
+
+  /**
+   * Create error for rate limiting on auth endpoints.
+   *
+   * @param {number} [retryAfter] - Seconds until retry is allowed
+   * @returns {AuthError}
+   */
+  static rateLimited(retryAfter) {
+    const message = retryAfter
+      ? `Too many attempts. Try again in ${Math.ceil(retryAfter / 60)} minutes.`
+      : 'Too many attempts. Please try again later.';
+
+    return new AuthError(message, 'AUTH_RATE_LIMITED', { retryAfter });
+  }
+
+  /**
+   * Create error for verification timeout.
+   *
+   * @returns {AuthError}
+   */
+  static verificationTimeout() {
+    return new AuthError(
+      'Email verification timed out. Please try again.',
+      'VERIFICATION_TIMEOUT',
+    );
+  }
+
+  /**
+   * Get JSON representation for API responses.
+   *
+   * @returns {object} JSON-serializable error object
+   */
+  toJSON() {
+    return {
+      error: 'AuthError',
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+
+/**
+ * Error thrown when buyer validation fails.
+ *
+ * Used when validate_buyer API indicates the user is not a paying customer.
+ *
+ * @see Story PRO-11 - Email Authentication & Buyer-Based Pro Activation
+ */
+class BuyerValidationError extends Error {
+  /**
+   * Create a BuyerValidationError.
+   *
+   * @param {string} message - Error message
+   * @param {string} [code] - Error code
+   * @param {object} [details] - Additional error details
+   */
+  constructor(message, code, details = {}) {
+    super(message);
+
+    this.name = 'BuyerValidationError';
+    this.code = code || 'BUYER_VALIDATION_FAILED';
+    this.details = details;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, BuyerValidationError);
+    }
+  }
+
+  /**
+   * Create error for non-buyer (validate_buyer returned false).
+   *
+   * @returns {BuyerValidationError}
+   */
+  static notABuyer() {
+    return new BuyerValidationError(
+      'No active Pro subscription found for this email.',
+      'NOT_A_BUYER',
+    );
+  }
+
+  /**
+   * Create error for buyer validation service failure.
+   *
+   * @returns {BuyerValidationError}
+   */
+  static serviceUnavailable() {
+    return new BuyerValidationError(
+      'Subscription verification service is temporarily unavailable. Please try again later.',
+      'BUYER_SERVICE_UNAVAILABLE',
+    );
+  }
+
+  /**
+   * Get JSON representation for API responses.
+   *
+   * @returns {object} JSON-serializable error object
+   */
+  toJSON() {
+    return {
+      error: 'BuyerValidationError',
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+
+module.exports = {
+  ProFeatureError,
+  LicenseActivationError,
+  LicenseValidationError,
+  AuthError,
+  BuyerValidationError,
+};