aios-core 4.2.13 → 4.2.15

package/pro/license/errors.js

@@ -1,450 +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,
-};
+/**
+ * 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,
+};